Anatomy of an extension
Every extension made with the SDK follows a standard file structure and includes a set of core files that make the extension work on Netlify. This page provides an introduction to the anatomy of an extension, including additional details for the optional functionality you might add.
Showcase extension
For a complete example of an extension and all of the files that make it work, refer to the Netlify extension showcase repository.
Extension file structure
Depending on which boilerplate options you select during the guided set-up flow, the SDK will generate all or a subset of the following files for you:
Endpoints
While there isn’t a stand-alone boilerplate option for Endpoints
, the SDK will automatically generate the /endpoints
directory for you when you select Build Event Handler
or Extension UI
. Alternatively, you can create the directory and save your endpoint files in it manually. Learn more about endpoints.
Core extension files
Every extension includes the following required files by default, regardless of which boilerplate option you choose:
File | Summary |
---|---|
src/index.ts | The entrypoint for developing the extension. This is where you create, configure, and export your extension. |
extension.yaml | The extension configuration file. This is where you configure extension metadata and declare extension surfaces for your extension UI. |
netlify.toml | The Netlify configuration file for the site that will host your extension. This is where you configure the settings for building and deploying your extension. |
package.json | The standard project file that contains metadata about your extension, the path to the entry file, dependencies, scripts, and more. |
details.md | The markdown file that Netlify renders on the extension’s details page in the Netlify UI after you publish the extension. This is where you add documentation for your users. |
All extensions need UI
When you create an extension, we recommend that you select the Extension UI
boilerplate at a minimum because all extensions need to define UI for users to configure their extension. Learn more about extension UI files in the section below.
src/index.ts
The Netlify SDK automatically generates a src/index.ts
file and specifies it as the main
entry file in the package.json
. The SDK uses this file as the entry point to load and bundle your extension.
If you update the filename, you must ensure that you update the main
field of the package.json
. For example, the filename may be src/entry.ts
, and the package.json
would include it as "main": "src/entry.ts"
.
The main entry file is where you include all of the code that configures your extension and related functionality. The file must export a valid NetlifyExtension
object.
extension.yaml
The extension.yaml
is the manifest file for your extension and it includes the following key values:
slug
: the slug for your extensionname
: the name of your extensionscopes
: the required permission scopes based on the boilerplate you selectedui
: a list of thesurfaces
that your extension UI contains
netlify.toml
One of the first steps in the publishing process is to deploy your extension as a site on Netlify.
The netlify.toml
is the Netlify configuration file that you use to configure the settings for building and deploying your extension on Netlify.
package.json
The automatically generated package.json
includes the following required fields:
name
: the name of your extensionmain
: the entry file for your extensiontype
: the package type, which must always bemodule
It also automatically includes the @netlify/sdk
dependency, along with related scripts for building and developing your extension.
details.md
The details.md
is a markdown file that you can use to add documentation for users on how to configure and use your extension. After you publish your extension, Netlify will render this markdown file on your extension’s details page in the Netlify UI.
Learn more about how to add documentation for your extension.
Extension UI files
When you select the Extension UI
boilerplate, the SDK generates the following extension UI and endpoint directories, with example files within them.
Note that the boilerplate comes with the tRPC integration configured for you. You can use the integration to write procedures and call them from your extension UI.
File | Summary |
---|---|
src/endpoints/ | The folder to store the endpoint files for your extension. The trpc.ts file initializes an endpoint that serves the tRPC router. |
server/ | The folder that contains the router.ts and trpc.ts files for the tRPC router and procedures. |
src/ui/ | The folder to store all of the related files for your extension’s UI, including the index.tsx , App.tsx , and your surfaces under /surfaces/ |
The SDK will also install the required modules and generate the related configuration files for each tool and library in the extension UI’s technical stack:
Tech stack
Learn more about each of these files in get started with extension UI and call endpoints from extension UI.
Build event handler files
When you select the Build Event Handler
boilerplate, the SDK includes the configuration for an example build event handler in src/index.ts
.
For example
The SDK also generates extension UI files required for a user to configure a build event handler.
Learn more in get started with build event handlers.
Connector files
When you select the Connector
boilerplate, the SDK includes the configuration for an example connector in src/index.ts
.
For example
Learn more in get started with connectors.
Edge function injection files
When you select the Edge Function Injection
boilerplate, the SDK generates the following edge functions directory and example file within it.
File | Summary |
---|---|
src/edge-functions/ | The folder to store edge functions in, with a sample edge function in hello-world.ts . |
Learn more in get started with edge function injection.
Function injection files
When you select the Functions Injection
boilerplate, the SDK generates the following functions directory and example file within it.
File | Summary |
---|---|
src/functions/ | The folder to store serverless functions in, with a sample function in hello-world.mts . |
Learn more in get started with function injection.