@tridion-sites/extensions-cli NPM

Tridion Sites Extensions CLI

Command-line interface to create, develop, build and package addons for Tridion Sites

Creating a new addon

$ npx @tridion-sites/extensions-cli@latest create

💡 Tip: Using @latest will ensure that the latest version of @tridion-sites/extensions-cli is used. See here for details.

The CLI will then provide a series of prompts, including the ID of the addon, the name of the frontend extension, and the URL for a compatible Tridion Sites installation. It will also automatically install all required dependencies.

Addon structure

After completing the prompts, CLI is going to create the following folder structure:

<addon_id>/
    <extension_name>/
        ...
    manifest.json
    <addon_id>.config.json

This structure allows you to have multiple extensions developed and packages together into a single addon. For example, you can have a backend extension that retrieves data from an external service and a frontend extension that defines how to present this data.

💡 Tip: For frontend-only addons you don't have to split functionality into separate projects as it is possible to define multiple frontend extensions in a single project. For more information see examples

The entry point for any addon is manifest.json. It contains all metadata information about the addon as well as about extensions included in it. You can find more information here

Optional config file is generated for every addon to simplify adding configuration options in the future.

💡 Tip: As the config file is optional by default, you can skip it when you deploy an addon package.

CLI also generates the folder structure for a frontend extension in a folder with the provided <extension_name>. The next section describes what is included in a frontend extension by default.

Frontend extension structure

<extension_name>/
    src/
        globals.ts
        index.ts
    .browserslistrc
    .editorconfig
    .eslintrc.json
    .gitignore
    .prettierrc
    babel.config.js
    debServer.js
    package.json
    tsconfig.json
    webpack.dev.config.js
    webpack.prod.config.js

File	Description
`src/globals.ts`	Provides access to global functionality: addon configuration, translations etc
`src/index.ts`	Entry point for the extension. Defines extension module
`.browserslistrc`	Specifies which browsers should be supported by the extension. Used by Babel
`.editorconfig`	Defines editor configuration that is supported by most IDEs. More info
`.eslintrc.json`	ESLint rules that address common code problems. Out of the box we provide rules for TypeScript, React hooks and imports
`.gitignore`	Allows to ignore folders and files when making Git commits so that they won't be pushed to the remote repository. More info
`.prettierrc`	Ensures consistent code style in the extension. Supported by most IDEs. More info about Prettier
`babel.config.js`	By default, the project is setup to use Babel for TypeScript compilation
`devServer.js`	Development server allows to develop extensions locally without deploying them to a remote environment
`package.json`	Manifest file for the frontend extension package. More info
`tsconfig.json`	Configuration used by TypeScript compiler. More info
`webpack.dev.config.js`	Development configuration for the Webpack bundler
`webpack.prod.config.js`	Production configuration for the Webpack bundler

All files or dependencies can be adjusted for the needs of a specific extension project. For example, adding a third-party component library or using CSS Modules

Important note: Do not update versions of existing packages in peerDependencies of package.json. These libraries are provided at runtime and a version mismatch might prevent your extension from running!

Developing a frontend extension

Frontend extensions are developed using React & TypeScript and make use of the @tridion-sites/extensions API.

First, let's switch into the extension folder

$ cd ./<extension-name>

💡 Tip: It is recommended to open your IDE in the extension directory so the root point is the extension itself.

As dependencies are installed automatically when you generate a new addon, you don't have to do any additional setup.

In order to add code for your extension, navigate to src/index.ts and update initialize method of the extension module. For example:

// Don't forget to use constants for build-in actions.
import { activitiesExplorerActionId } from '@tridion-sites/extensions';

const extensionModule: ExtensionModule = {
    runtimeInfo: packageJson as RuntimeInformation,
    initializeGlobals,
    initialize: builder => {
        // This is going to remove `Refresh` action from the context menu of Content Explorer Table
        builder.contentExplorer.table.contextMenu.removeAction(activitiesExplorerActionId.refresh);
    },
};

Now let's run the extension

$ npm run dev

This is going to start a development server on localhost:3000 by default and show your extension on the target environment that you provided while creating the addon.

Important note: When making changes that might result in changes to the dist package (adding or removing files) make sure the files array in the manifest.json is updated.

Packaging an addon

When the extension is ready, first run npm run build. This command outputs into /dist folder in the addon folder (one level above the extension folder). In order to simplify the packing procedure every frontend extension outputs results into the same /dist folder.

After all extensions are built, run npm run pack inside any extension folder to package the addon for use with Tridion Sites.