@tridion-sites/extensions-cli 1.0.1 → 1.0.3

package/README.md

@@ -1,16 +1,124 @@
 # Tridion Sites Extensions CLI
 
-Command-line interface to create, develop, build and package extensions for Tridion Sites
-
-## Features
+Command-line interface to create, develop, build and package addons for Tridion Sites
 
 ## Creating a new addon
 
 ```bash
-$ npx @tridion-sites/extensions-cli create
+$ 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](https://github.com/npm/cli/issues/4108) 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](https://github.com/RWS/tridion-sites-extensions-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`](https://docs.rws.com/986894/707998/tridion-sites-9-6-main-documentation/basic-structure-of-the-add-on-manifest-file)
+
+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](https://babeljs.io/docs/babel-preset-env#browserslist-integration)                 |
+| `.editorconfig`          | Defines editor configuration that is supported by most IDEs. [More info](https://editorconfig.org/)                                                               |
+| `.eslintrc.json`         | [ESLint](https://eslint.org/) 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](https://git-scm.com/docs/gitignore) |
+| `.prettierrc`            | Ensures consistent code style in the extension. Supported by most IDEs. More info about [Prettier](https://prettier.io/)                                          |
+| `babel.config.js`        | By default, the project is setup to use [Babel](https://babeljs.io/) 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](https://docs.npmjs.com/about-packages-and-modules#about-packages)                                   |
+| `tsconfig.json`          | Configuration used by TypeScript compiler. [More info](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html)                                           |
+| `webpack.dev.config.js`  | Development configuration for the [Webpack bundler](https://webpack.js.org/)                                                                                      |
+| `webpack.prod.config.js` | Production configuration for the [Webpack bundler](https://webpack.js.org/)                                                                                       |
+
+All files or dependencies can be adjusted for the needs of a specific extension project. For example, adding a [third-party component library](https://github.com/RWS/tridion-sites-extensions-examples/blob/main/activities-explorer/work-items-column-addon/work-items-column/package.json#L29) or [using CSS Modules](https://github.com/RWS/tridion-sites-extensions-examples/tree/main/primary-navigation/async-page-addon/async-page)
+
+**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`](https://react.dev/) & [`TypeScript`](https://www.typescriptlang.org/docs/handbook/intro.html) and make use of the `@tridion-sites/extensions` API.
+
+First, let's switch into the extension folder
+
+```bash
+$ 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:
+
+```typescript
+// 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
+
+```bash
+$ npm run dev
 ```
 
-## API Documentation
+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.
 
-Documentation for all available services, their methods and interfaces can be found at
-http://developers.rws.com/tridion-sites-extensions-api-docs/open-api-client.html
+After all extensions are built, run `npm run pack` inside any extension folder to package the addon for use with Tridion Sites.

package/dist/addon/template/extension/.eslintrc.json.hbs

@@ -13,7 +13,7 @@
         "plugin:react-hooks/recommended",
         "prettier"
     ],
-    "plugins": ["react", "@typescript-eslint"],
+    "plugins": ["@typescript-eslint", "react", "simple-import-sort", "unused-imports"],
     "env": {
         "es6": true,
         "browser": true
@@ -24,7 +24,16 @@
         }
     },
     "rules": {
+        "@typescript-eslint/consistent-type-imports": ["warn"],
         "@typescript-eslint/no-unused-vars": "off",
-        "import/no-default-export": "off"
+        "import/no-default-export": "off",
+        "simple-import-sort/imports": [
+            "error",
+            {
+                "groups": [["^\\u0000"], ["^@?\\w"], ["^@(.*|$)"], ["^[^.]"], ["^\\."]]
+            }
+        ],
+        "unused-imports/no-unused-imports": "error",
+        "unused-imports/no-unused-vars": "off"
     }
 }

package/dist/addon/template/extension/package.json.hbs

@@ -50,6 +50,8 @@
         "eslint-formatter-pretty": "5.0.0",
         "eslint-plugin-react": "7.32.2",
         "eslint-plugin-react-hooks": "4.6.0",
+        "eslint-plugin-simple-import-sort": "9.0.0",
+        "eslint-plugin-unused-imports": "2.0.0",
         "fork-ts-checker-webpack-plugin": "8.0.0",
         "prettier": "2.8.8",
         "react": "18.2.0",

package/dist/addon/template/extension/webpack.dev.config.js.hbs

@@ -8,7 +8,7 @@ import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin';
 /** @type { import('webpack').Configuration } */
 export default env => ({
     mode: 'development',
-    entry: './src/index.tsx',
+    entry: './src/index.ts',
     output: {
         library: {
             type: 'system',

package/dist/addon/template/extension/webpack.prod.config.js.hbs

@@ -6,7 +6,7 @@ import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin';
 /** @type { import('webpack').Configuration } */
 export default {
     mode: 'production',
-    entry: './src/index.tsx',
+    entry: './src/index.ts',
     output: {
         library: {
             type: 'system',

package/dist/cli.js

@@ -76,7 +76,7 @@ const copyTemplate = ({ addonId, addonRootFolderPath, author, extensionDescripti
         'devServer.js',
         'tsconfig.json',
         'src/globals.ts',
-        'src/index.tsx',
+        'src/index.ts',
     ].forEach(fileName => {
         createFileFromTemplate(resolve(templatePath, `extension/${fileName}.hbs`), resolve(extensionRootFolderPath, fileName));
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tridion-sites/extensions-cli",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "CLI to create, develop, build and package extensions for Tridion Sites",
   "author": "RWS",
   "homepage": "https://www.rws.com",
@@ -24,7 +24,7 @@
     "test": "sites-extensions"
   },
   "dependencies": {
-    "@tridion-sites/extensions": "1.0.1",
+    "@tridion-sites/extensions": "1.0.2",
     "@tridion-sites/models": "1.0.0",
     "@tridion-sites/open-api-client": "2.0.0",
     "archiver": "5.3.1",