@remkoj/optimizely-cms-cli 6.0.0-pre8 → 6.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +348 -38
  2. package/dist/index.js +1548 -911
  3. package/dist/index.js.map +1 -1
  4. package/package.json +20 -16
package/README.md CHANGED
@@ -1,4 +1,8 @@
1
1
  # Optimizely CMS Command Line Toolkit <!-- omit in toc -->
2
+
3
+ > [!WARNING]
4
+ > There'll be an update of Optimizely SaaS CMS that is incompatible with all SDK versions prior to 5.1.6. If you don't upgrade, you will see empty pages (main website) and "Component not found" messages (preview).
5
+
2
6
  A collection of Command Line tools used to increase productivity when working with the Optimizely CMS from a TypeScript / JavaScript based frontend.
3
7
 
4
8
  The defaults and methods are based upon using a Next.JS application with the conventions introduced by the [Create Next App template](https://github.com/remkoj/optimizely-saas-starter)
@@ -10,11 +14,6 @@ The defaults and methods are based upon using a Next.JS application with the con
10
14
  - [2.1. Global parameters](#21-global-parameters)
11
15
  - [2.2. Environment variables](#22-environment-variables)
12
16
  - [3. Available commands](#3-available-commands)
13
- - [3.1. General CMS Commands](#31-general-cms-commands)
14
- - [3.2. JSON Schema's and Schema Validation](#32-json-schemas-and-schema-validation)
15
- - [3.3. Display Templates (Styles)](#33-display-templates-styles)
16
- - [3.4. Content Types](#34-content-types)
17
- - [3.5. Next.JS Project support](#35-nextjs-project-support)
18
17
  - [4. Detailed command descriptions](#4-detailed-command-descriptions)
19
18
  - [4.1. Generate React Component Factory](#41-generate-react-component-factory)
20
19
 
@@ -72,38 +71,349 @@ All commands share these parameters that configure the frontend environment.
72
71
  This CLI tool shares the environment variables with [@remkoj/optimizely-cms-api](https://www.npmjs.com/package/@remkoj/optimizely-cms-api). When starting the CLI tool, it looks for `.env` and `.env.local` to extend the environment variables and thus works using the Next.JS conventions.
73
72
 
74
73
  ## 3. Available commands
75
- The following commands are available, you can always run `opti-cms --help` or `opti-cms [command] --help` to see all information for the CLI utility or command. If the command is omitted, the CLI will assume the `cms:version` command.
76
-
77
- ### 3.1. General CMS Commands
78
- | Command | Description |
79
- | --- | --- |
80
- |`cms:version`| Fetch and display the version of the CMS from the endpoint, allowing validation of the connection with Optimizely CMS. |
81
- |`cms:reset` | Reset the CMS instance by removing all Content, Content Types and Display Templates.<br/>***Note:*** This currently requires some manual steps, the CLI will provide the needed guidance on these manual steps. |
82
-
83
- ### 3.2. JSON Schema's and Schema Validation
84
- | Command | Description |
85
- | --- | --- |
86
- | `schema:download` | Download schema definitions into a `.schema` folder within your project to facilitate JSON Schema validation by your IDE of choice. Use one or more `-s [schemaName]` parameters to override the schemas that must be downloaded. The `-d [relativePath]` to change where the location where the schema files must be stored. Using `-f` enables overwriting of existing schema files. |
87
- | `schema:list` | Display a list of all schema's available within the Optimizely CMS instance.
88
- | `schema:validate` | Downloads the OpenAPI Specification from the configured Optimizely CMS instance, extracts the appropriate types from it and uses those to validate all `*.opti-style.json` and `*.opti-type.json` files in the project. The output provides detailled error messages for each file that is not valid. |
89
- | `schema:vscode` | Updates the `.vscode` folder to include the JSON Schema for both Content Type defintions and Display Templates. This will also create or update the `settings.json` to enable code-completion and validation on `*.opti-style.json` and `*.opti-type.json` files, using these schema's. Rerun this command to ensure that the definitions remain in sync with the OpenAPI specification of the CMS API. |
90
-
91
- ### 3.3. Display Templates (Styles)
92
- | Command | Description |
93
- | --- | --- |
94
- | `style:create` | Create a new Style definition file *(and optionally create it immediately within the CMS as well)* using a CLI interface, that will guide you through the process of setting the required properties.<br/>***Visual Studio Code users:*** Running `yarn opti-cms schema:vscode` will enable VS-Code to provide validation and completion for the generated `*.opti-style.json` file. |
95
-
96
- ### 3.4. Content Types
97
- | Command | Description |
98
- | --- | --- |
99
- |`types:pull`| Read all existing content types from the Optimizely CMS and create their representation within the codebase. Use the parameters of this method to control which types will be pulled and to allow overwriting of existing files. |
100
- |`types:push`| Create or overwrite the content type defintions from the codebase into Optimizely CMS, use the parameters of this method to control which types will be transferred and whether destructive changes are allowed. |
101
-
102
- ### 3.5. Next.JS Project support
103
- | Command | Description |
104
- | --- | --- |
105
- | `nextjs:factory` | Generate the component factories needed for suggested implementation pattern of Optimizely CMS in Next.JS. See [4.1. Generate React Component Factory](#41-generate-react-component-factory) |
106
- | `nextjs:create` | An conveniance command, that will run the appropriate commands from the CLI in the right order to fully scaffold a frontend based upon the Content Types and Display Templates that already exist within the Optimizely CMS instance.<br/>It runs these commands: `types:pull`, `styles:pull`, `nextjs:fragments` `nextjs:components`, `nextjs:visualbuilder` and `nextjs:factory`. The command line arguments you provide to `nextjs:create` will be forwarded to each of these commands. |
74
+ The following commands are currently available in `src/commands`. Use `yarn opti-cms [command] --help` for runtime help.
75
+
76
+ All commands also support the [global parameters](#21-global-parameters).
77
+
78
+ ### `cms:*`
79
+ | Command | Description | Usage |
80
+ | --- | --- | --- |
81
+ | `cms:reset` | Completely clear & reset the CMS Database | `yarn opti-cms cms:reset` |
82
+ | `cms:version` | Get the CMS Version information | `yarn opti-cms cms:version` |
83
+
84
+ ### `project:*`
85
+ | Command | Description | Usage |
86
+ | --- | --- | --- |
87
+ | `project:migrate` | Automate the directory naming convention update | `yarn opti-cms project:migrate` |
88
+
89
+ ### `nextjs:*`
90
+ | Command | Description | Usage |
91
+ | --- | --- | --- |
92
+ | `nextjs:components` | Create the React Components for a Next.JS / Optimizely Graph structure | `yarn opti-cms nextjs:components` |
93
+ | `nextjs:create` | Scaffold a complete Next.JS / Optimizely Graph structure | `yarn opti-cms nextjs:create` |
94
+ | `nextjs:factory` | Create the ComponentFactory for a Next.JS / Optimizely Graph structure | `yarn opti-cms nextjs:factory` |
95
+ | `nextjs:fragments` | Create the GrapQL Fragments for a Next.JS / Optimizely Graph structure | `yarn opti-cms nextjs:fragments` |
96
+ | `nextjs:queries` | Create the GrapQL Queries to use two queries to load content | `yarn opti-cms nextjs:queries` |
97
+ | `nextjs:visualbuilder` | Create the React Components for Visual Builder in a Next.JS / Optimizely Graph structure | `yarn opti-cms nextjs:visualbuilder` |
98
+
99
+ ### `schema:*`
100
+ | Command | Description | Usage |
101
+ | --- | --- | --- |
102
+ | `schema:download` | Create JSON schema files for selected types | `yarn opti-cms schema:download` |
103
+ | `schema:list` | List all schema's that are available within the SaaS CMS instance | `yarn opti-cms schema:list` |
104
+ | `schema:validate` | Validate the opti-type.json & opti-style.json files | `yarn opti-cms schema:validate` |
105
+ | `schema:vscode` | Configure schema validation for opti-type.json & opti-style.json files by VSCode | `yarn opti-cms schema:vscode` |
106
+
107
+ ### `style*` and `styles:*`
108
+ | Command | Description | Usage |
109
+ | --- | --- | --- |
110
+ | `style:create` | Create a new style definition | `yarn opti-cms style:create` |
111
+ | `styles:delete` | Remove Visual Builder style definitions from the CMS | `yarn opti-cms styles:delete` |
112
+ | `styles:list` | List Visual Builder style definitions from the CMS | `yarn opti-cms styles:list` |
113
+ | `styles:pull` | Create Visual Builder style definitions from the CMS | `yarn opti-cms styles:pull` |
114
+ | `styles:push` | Push Visual Builder style definitions into the CMS (create/replace) | `yarn opti-cms styles:push` |
115
+
116
+ ### `types:*`
117
+ | Command | Description | Usage |
118
+ | --- | --- | --- |
119
+ | `types:pull` | Pull content type definition files into the project | `yarn opti-cms types:pull` |
120
+ | `types:push` | Push content type definition into Optimizely CMS (create / replace) | `yarn opti-cms types:push` |
121
+
122
+ ### `cms:reset`
123
+ Description: Completely clear & reset the CMS database.
124
+
125
+ Usage:
126
+ ```bash
127
+ yarn opti-cms cms:reset
128
+ ```
129
+
130
+ Parameters: no command-specific parameters (global parameters still apply).
131
+
132
+ ### `cms:version`
133
+ Description: Get CMS version and service info.
134
+
135
+ Usage:
136
+ ```bash
137
+ yarn opti-cms cms:version
138
+ ```
139
+
140
+ Parameters: no command-specific parameters (global parameters still apply).
141
+
142
+ ### `project:migrate`
143
+ Description: Rename folders/files to match the updated naming conventions and regenerate factories.
144
+
145
+ Usage:
146
+ ```bash
147
+ yarn opti-cms project:migrate [options]
148
+ ```
149
+
150
+ | Parameter | Alias | Optional | Default | Usage |
151
+ | --- | --- | --- | --- | --- |
152
+ | `--excludeTypes` | `--ect` | Yes | `['folder','media','image','video']` | Exclude content type keys while preparing context |
153
+ | `--excludeBaseTypes` | `--ebt` | Yes | `[]` | Exclude content base types while preparing context |
154
+ | `--baseTypes` | `-b` | Yes | `[]` | Include only selected base types |
155
+ | `--types` | `-t` | Yes | `[]` | Include only selected content types |
156
+ | `--all` | `-a` | Yes | `false` | Include unsupported base types |
157
+ | `--force` | `-f` | Yes | `false` | Overwrite generated files where applicable |
158
+
159
+ ### `nextjs:components`
160
+ Description: Generate React component stubs for selected content types.
161
+
162
+ Usage:
163
+ ```bash
164
+ yarn opti-cms nextjs:components [options]
165
+ ```
166
+
167
+ | Parameter | Alias | Optional | Default | Usage |
168
+ | --- | --- | --- | --- | --- |
169
+ | `--excludeTypes` | `--ect` | Yes | `['folder','media','image','video']` | Exclude content type keys |
170
+ | `--excludeBaseTypes` | `--ebt` | Yes | `[]` | Exclude content base types |
171
+ | `--baseTypes` | `-b` | Yes | `[]` | Include only selected base types |
172
+ | `--types` | `-t` | Yes | `[]` | Include only selected content type keys |
173
+ | `--all` | `-a` | Yes | `false` | Include unsupported base types |
174
+ | `--force` | `-f` | Yes | `false` | Overwrite existing files |
175
+
176
+ ### `nextjs:create`
177
+ Description: Run the full Next.js scaffold flow from CMS definitions.
178
+
179
+ Usage:
180
+ ```bash
181
+ yarn opti-cms nextjs:create [options]
182
+ ```
183
+
184
+ | Parameter | Alias | Optional | Default | Usage |
185
+ | --- | --- | --- | --- | --- |
186
+ | `--excludeTypes` | `--ect` | Yes | `['folder','media','image','video']` | Exclude content type keys |
187
+ | `--excludeBaseTypes` | `--ebt` | Yes | `[]` | Exclude content base types |
188
+ | `--baseTypes` | `-b` | Yes | `[]` | Include only selected base types |
189
+ | `--types` | `-t` | Yes | `[]` | Include only selected content type keys |
190
+ | `--all` | `-a` | Yes | `false` | Include unsupported base types |
191
+ | `--force` | `-f` | Yes | `false` | Overwrite existing generated files |
192
+
193
+ ### `nextjs:factory`
194
+ Description: Generate component factory files.
195
+
196
+ Usage:
197
+ ```bash
198
+ yarn opti-cms nextjs:factory [options]
199
+ ```
200
+
201
+ | Parameter | Alias | Optional | Default | Usage |
202
+ | --- | --- | --- | --- | --- |
203
+ | `--excludeTypes` | `--ect` | Yes | `['folder','media','image','video']` | Exclude content type keys |
204
+ | `--excludeBaseTypes` | `--ebt` | Yes | `[]` | Exclude content base types |
205
+ | `--baseTypes` | `-b` | Yes | `[]` | Include only selected base types |
206
+ | `--types` | `-t` | Yes | `[]` | Include only selected content type keys |
207
+ | `--all` | `-a` | Yes | `false` | Include unsupported base types |
208
+ | `--force` | `-f` | Yes | `false` | Overwrite existing generated files |
209
+
210
+ ### `nextjs:fragments`
211
+ Description: Generate GraphQL fragments for selected content types.
212
+
213
+ Usage:
214
+ ```bash
215
+ yarn opti-cms nextjs:fragments [options]
216
+ ```
217
+
218
+ | Parameter | Alias | Optional | Default | Usage |
219
+ | --- | --- | --- | --- | --- |
220
+ | `--excludeTypes` | `--ect` | Yes | `['folder','media','image','video']` | Exclude content type keys |
221
+ | `--excludeBaseTypes` | `--ebt` | Yes | `[]` | Exclude content base types |
222
+ | `--baseTypes` | `-b` | Yes | `[]` | Include only selected base types |
223
+ | `--types` | `-t` | Yes | `[]` | Include only selected content type keys |
224
+ | `--all` | `-a` | Yes | `false` | Include unsupported base types |
225
+ | `--force` | `-f` | Yes | `false` | Overwrite existing generated files |
226
+
227
+ ### `nextjs:queries`
228
+ Description: Generate GraphQL queries (defaults to page/experience base types).
229
+
230
+ Usage:
231
+ ```bash
232
+ yarn opti-cms nextjs:queries [options]
233
+ ```
234
+
235
+ | Parameter | Alias | Optional | Default | Usage |
236
+ | --- | --- | --- | --- | --- |
237
+ | `--excludeTypes` | `--ect` | Yes | `['folder','media','image','video']` | Exclude content type keys |
238
+ | `--excludeBaseTypes` | `--ebt` | Yes | `[]` | Exclude content base types |
239
+ | `--baseTypes` | `-b` | Yes | `['page','experience']` | Include only selected base types |
240
+ | `--types` | `-t` | Yes | `[]` | Include only selected content type keys |
241
+ | `--all` | `-a` | Yes | `false` | Include unsupported base types |
242
+ | `--force` | `-f` | Yes | `false` | Overwrite existing generated files |
243
+
244
+ ### `nextjs:visualbuilder`
245
+ Description: Generate Visual Builder components and node templates.
246
+
247
+ Usage:
248
+ ```bash
249
+ yarn opti-cms nextjs:visualbuilder [options]
250
+ ```
251
+
252
+ | Parameter | Alias | Optional | Default | Usage |
253
+ | --- | --- | --- | --- | --- |
254
+ | `--excludeTypes` | `--ect` | Yes | `['folder','media','image','video']` | Exclude content type keys |
255
+ | `--excludeBaseTypes` | `--ebt` | Yes | `[]` | Exclude content base types |
256
+ | `--baseTypes` | `-b` | Yes | `[]` | Include only selected base types |
257
+ | `--types` | `-t` | Yes | `[]` | Include only selected content type keys |
258
+ | `--all` | `-a` | Yes | `false` | Include unsupported base types |
259
+ | `--force` | `-f` | Yes | `false` | Overwrite existing generated files |
260
+
261
+ ### `schema:download`
262
+ Description: Download JSON schema files from the CMS OpenAPI specification.
263
+
264
+ Usage:
265
+ ```bash
266
+ yarn opti-cms schema:download [options]
267
+ ```
268
+
269
+ | Parameter | Alias | Optional | Default | Usage |
270
+ | --- | --- | --- | --- | --- |
271
+ | `--schemaDir` | `-d` | Yes | `'./.schema'` | Target schema directory relative to project root |
272
+ | `--schemas` | `-s` | Yes | `['DisplayTemplate','ContentType']` | Schema names to download |
273
+ | `--force` | `-f` | Yes | `false` | Overwrite existing schema files |
274
+
275
+ ### `schema:list`
276
+ Description: List schemas exposed by the CMS OpenAPI specification.
277
+
278
+ Usage:
279
+ ```bash
280
+ yarn opti-cms schema:list
281
+ ```
282
+
283
+ Parameters: no command-specific parameters (global parameters still apply).
284
+
285
+ ### `schema:validate`
286
+ Description: Validate `*.opti-type.json` and `*.opti-style.json` files against CMS schemas.
287
+
288
+ Usage:
289
+ ```bash
290
+ yarn opti-cms schema:validate
291
+ ```
292
+
293
+ Parameters: no command-specific parameters (global parameters still apply).
294
+
295
+ ### `schema:vscode`
296
+ Description: Configure VS Code schema mappings for Optimizely type/style JSON files.
297
+
298
+ Usage:
299
+ ```bash
300
+ yarn opti-cms schema:vscode
301
+ ```
302
+
303
+ Parameters: no command-specific parameters (global parameters still apply).
304
+
305
+ ### `style:create`
306
+ Description: Interactive wizard to create a new style definition.
307
+
308
+ Usage:
309
+ ```bash
310
+ yarn opti-cms style:create
311
+ ```
312
+
313
+ Parameters: no command-specific parameters (global parameters still apply).
314
+
315
+ ### `styles:delete`
316
+ Description: Delete display templates from CMS and optionally update/remove local files.
317
+
318
+ Usage:
319
+ ```bash
320
+ yarn opti-cms styles:delete [options]
321
+ ```
322
+
323
+ | Parameter | Alias | Optional | Default | Usage |
324
+ | --- | --- | --- | --- | --- |
325
+ | `--excludeTypes` | `--ect` | Yes | `['folder','media','image','video']` | Exclude content type keys |
326
+ | `--excludeBaseTypes` | `--ebt` | Yes | `[]` | Exclude content base types |
327
+ | `--baseTypes` | `-b` | Yes | `[]` | Include only selected base types |
328
+ | `--types` | `-t` | Yes | `[]` | Include only selected content type keys |
329
+ | `--all` | `-a` | Yes | `false` | Include unsupported base types |
330
+ | `--excludeNodeTypes` | `--ent` | Yes | `[]` | Exclude node types |
331
+ | `--excludeTemplates` | `--et` | Yes | `['folder','media','image','video']` | Exclude style template keys |
332
+ | `--nodes` | `-n` | Yes | `[]` | Include only selected node types |
333
+ | `--templates` | `-d` | Yes | `[]` | Include only selected templates |
334
+ | `--templateTypes` | `--tt` | Yes | `[]` | Include only selected template types (`node`,`base`,`component`) |
335
+ | `--force` | `-f` | Yes | `false` | Execute deletion (otherwise preview) |
336
+ | `--withStyleFile` | `-w` | Yes | `true` | Delete local `*.opti-style.json` files |
337
+ | `--definitions` | `-u` | Yes | `true` | Update/remove generated TypeScript display template definitions |
338
+
339
+ ### `styles:list`
340
+ Description: List display templates from CMS.
341
+
342
+ Usage:
343
+ ```bash
344
+ yarn opti-cms styles:list
345
+ ```
346
+
347
+ Parameters: no command-specific parameters (global parameters still apply).
348
+
349
+ ### `styles:pull`
350
+ Description: Pull display templates from CMS and generate style files/helpers.
351
+
352
+ Usage:
353
+ ```bash
354
+ yarn opti-cms styles:pull [options]
355
+ ```
356
+
357
+ | Parameter | Alias | Optional | Default | Usage |
358
+ | --- | --- | --- | --- | --- |
359
+ | `--excludeTypes` | `--ect` | Yes | `['folder','media','image','video']` | Exclude content type keys |
360
+ | `--excludeBaseTypes` | `--ebt` | Yes | `[]` | Exclude content base types |
361
+ | `--baseTypes` | `-b` | Yes | `[]` | Include only selected base types |
362
+ | `--types` | `-t` | Yes | `[]` | Include only selected content type keys |
363
+ | `--all` | `-a` | Yes | `false` | Include unsupported base types |
364
+ | `--excludeNodeTypes` | `--ent` | Yes | `[]` | Exclude node types |
365
+ | `--excludeTemplates` | `--et` | Yes | `['folder','media','image','video']` | Exclude style template keys |
366
+ | `--nodes` | `-n` | Yes | `[]` | Include only selected node types |
367
+ | `--templates` | `-d` | Yes | `[]` | Include only selected templates |
368
+ | `--templateTypes` | `--tt` | Yes | `[]` | Include only selected template types (`node`,`base`,`component`) |
369
+ | `--force` | `-f` | Yes | `false` | Overwrite existing files |
370
+ | `--definitions` | `-u` | Yes | `true` | Create/update generated TypeScript display template definitions |
371
+
372
+ ### `styles:push`
373
+ Description: Push local style definitions into CMS.
374
+
375
+ Usage:
376
+ ```bash
377
+ yarn opti-cms styles:push [options]
378
+ ```
379
+
380
+ | Parameter | Alias | Optional | Default | Usage |
381
+ | --- | --- | --- | --- | --- |
382
+ | `--excludeTemplates` | `-e` | Yes | `[]` | Exclude template keys from push |
383
+ | `--templates` | `-t` | Yes | `[]` | Include only selected template keys |
384
+
385
+ ### `types:pull`
386
+ Description: Pull content type definitions from CMS to local files.
387
+
388
+ Usage:
389
+ ```bash
390
+ yarn opti-cms types:pull [options]
391
+ ```
392
+
393
+ | Parameter | Alias | Optional | Default | Usage |
394
+ | --- | --- | --- | --- | --- |
395
+ | `--excludeTypes` | `--ect` | Yes | `['folder','media','image','video']` | Exclude content type keys |
396
+ | `--excludeBaseTypes` | `--ebt` | Yes | `[]` | Exclude content base types |
397
+ | `--baseTypes` | `-b` | Yes | `[]` | Include only selected base types |
398
+ | `--types` | `-t` | Yes | `[]` | Include only selected content type keys |
399
+ | `--all` | `-a` | Yes | `false` | Include unsupported base types |
400
+ | `--force` | `-f` | Yes | `false` | Overwrite existing files |
401
+
402
+ ### `types:push`
403
+ Description: Push local content type definitions to CMS.
404
+
405
+ Usage:
406
+ ```bash
407
+ yarn opti-cms types:push [options]
408
+ ```
409
+
410
+ | Parameter | Alias | Optional | Default | Usage |
411
+ | --- | --- | --- | --- | --- |
412
+ | `--force` | `-f` | Yes | `false` | Overwrite/replace while pushing |
413
+ | `--excludeTypes` | `--ect` | Yes | `[]` | Exclude content type keys |
414
+ | `--excludeBaseTypes` | `--ebt` | Yes | `['folder','media','image','video']` | Exclude content base types |
415
+ | `--baseTypes` | `-b` | Yes | `[]` | Include only selected base types |
416
+ | `--types` | `-t` | Yes | `[]` | Include only selected content type keys |
107
417
 
108
418
  ## 4. Detailed command descriptions
109
419
  ### 4.1. Generate React Component Factory
@@ -123,4 +433,4 @@ yarn opti-cms nextjs:factory -f
123
433
  | --baseTypes | -b | Select only content types with one of these base types. Add multiple times to build a list | [] |
124
434
  | --types | -t | Select content types with this key. Add multiple times to build a list | [] |
125
435
  | --all | -a | Include non-supported base types, non supported base types are skipped by default | |
126
- | --force | -f | By default, this method is none-destructive. Set this parameter to overwrite existing files. | |
436
+ | --force | -f | By default, this method is none-destructive. Set this parameter to overwrite existing files. | |