diff --git a/README.md b/README.md index b614027..05e8e35 100644 --- a/README.md +++ b/README.md @@ -1,118 +1,67 @@ -![](/.github/assets/repo-banner.png) -
-

Storyblok CLI

-

A powerful CLI for scaffolding Storyblok projects and fieldtypes.

+ +![Storyblok ImagoType](https://raw.githubusercontent.com/storyblok/.github/refs/heads/main/profile/public/github-banner.png) + +

Storyblok CLI

+

A powerful CLI tool to improve the DX of your Storyblok projects.


- Storyblok JS + Storyblok JS Client - npm + npm -

- -

- + - Follow @Storyblok - - - Follow @Storyblok + Follow @Storyblok +
+ + Follow @Storyblok

+## Features + +- 🛡️ **Type Safety** - Generate TypeScript type definitions for your Storyblok components, ensuring type safety in your frontend applications +- 🔐 **Authentication** - Secure login system with support for different regions and CI environments +- 🧩 **Component Management** - Pull and push component schemas, groups, presets, and internal tags between spaces +- 🔄 **Migration System** - Generate and run migrations to transform or update field values across your Storyblok content +- 🌐 **Language Management** - Pull and manage languages for your Storyblok space +- 📁 **File Organization** - Organized file structure with the `.storyblok` directory as default +- 🛠️ **Customizable Paths** - Flexible path configuration for all generated files +- 📝 **Naming Conventions** - Consistent file naming with customizable suffixes and prefixes +- 📂 **Separate Files Support** - Option to work with individual component files or consolidated files +- 👀 **Dry Run Mode** - Preview migrations changes before applying them to your Storyblok space +- 🔍 **Filtering Capabilities** - Filter components and stories using glob patterns and Storyblok query syntax +- 📊 **Verbose Logging** - Improved error handling and detailed logging options for debugging and monitoring + ## Pre-requisites - [Node.js >= 18.0.0](https://nodejs.org/en/download/) - Storyblok account (sign up [here](https://app.storyblok.com/#!/signup?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-cli)) - Personal access token from Storyblok (get it [here](https://app.storyblok.com/#/me/account?tab=token)) -## 🚀 Usage - -### Installation - -```bash -npm install storyblok -g -``` - -If you prefer not to install the package globally you can use `npx`: - -```bash -npx storyblok -``` - -## Breaking Changes ⚠️ - -### `.storyblok` directory as default - -All the commands that generate files will now use the `.storyblok` directory as the default directory to interact with those files. This aims to encapsulate all Storyblok CLI operations instead of filling them on the root. Users would be able to customize the directory by using the `--path` flag. - -Example: - -```bash -storyblok pull-languages --space=12345 -``` - -Will generate the languages in the `.storyblok/languages` directory. - -> [!TIP] -> If you prefer to avoid pushing the `.storyblok` directory to your repository you can add it to your `.gitignore` file. - -### Generated filename syntax conventions - -The generated files will now follow a more consistent naming convention. The files will be named using the following syntax: - -``` -.. -``` +## Documentation -Where: - -- `` is the name of the file. Customizable by the user with the `--filename` flag -- `` is an optional suffix to differentiate the files. By default is going to be the `spaceId` and is customizable by the user with the `--suffix` flag -- `` is the file extension. By default is `json` (Not configurable) - -Example: - -```bash -storyblok pull-languages --space=12345 --filename=my-languages --suffix=dev -``` - -Will generate the languages in the following path `.storyblok/languages/my-languages.dev.json` - -If you would like to use a timestamp as the suffix you can use: - -```bash -storyblok pull-languages --space=12345 --filename=my-languages --suffix="$(date +%s)" -``` - -> [!WARNING] -> The `--filename` will be ignored in the case that `--separate-files` is used on the commands that supports it. +For complete documentation, please visit [https://storyblok.com/docs](https://storyblok.com/docs/packages/my-joyful-package) ## Setup -First clone the repository and install the dependencies: +This package relies on [pnpm](https://pnpm.io/) to manage dependencies. For instructions on how to install pnpm, please visit [pnpm.io](https://pnpm.io/installation). ```bash pnpm install ``` -Then you can stub and run the CLI with: - -```bash -pnpm run dev -``` - -For example: +## Build ```bash -pnpm run dev login +pnpm build ``` ### Testing @@ -145,7 +94,35 @@ Then you can set breakpoints directly to the typescript files and the debugger w ![Debugging](/.github/assets/breakpoints.png) -### Contributing +## Community + +For help, discussion about best practices, or any other conversation that would benefit from being searchable: + +- [Discuss Storyblok on Github Discussions](https://github.com/storyblok/storyblok/discussions) + +For community support, chatting with other users, please visit: + +- [Discuss Storyblok on Discord](https://discord.gg/jKrbAMz) + +## Support + +For bugs or feature requests, please [submit an issue](https://github.com/storyblok/my-joyful-package/issues/new/choose). + +> [!IMPORTANT] +> Please search existing issues before submitting a new one. Issues without a minimal reproducible example will be closed. [Why reproductions are Required](https://antfu.me/posts/why-reproductions-are-required). + +### I can't share my company project code + +We understand that you might not be able to share your company's project code. Please provide a minimal reproducible example that demonstrates the issue by using tools like [Stackblitz](https://stackblitz.com) or a link to a Github Repo lease make sure you include a README file with the instructions to build and run the project, important not to include any access token, password or personal information of any kind. + +### I only have a question + +If you have a question, please ask in the [Discuss Storyblok on Discord](https://discord.gg/jKrbAMz) channel. + +## Contributing + +If you're interested in contributing to my-joyful-package, please read our [contributing docs](https://github.com/storyblok/.github/blob/main/CONTRIBUTING.md) before submitting a pull request. + +## License -Please see our [contributing guidelines](https://github.com/storyblok/.github/blob/main/contributing.md) and our [code of conduct](https://www.storyblok.com/trust-center#code-of-conduct?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-js). -This project use [semantic-release](https://semantic-release.gitbook.io/semantic-release/) for generate new versions by using commit messages and we use the Angular Convention to naming the commits. Check [this question](https://semantic-release.gitbook.io/semantic-release/support/faq#how-can-i-change-the-type-of-commits-that-trigger-a-release) about it in semantic-release FAQ +[License](/LICENSE) diff --git a/src/commands/types/generate/README.md b/src/commands/types/generate/README.md new file mode 100644 index 0000000..ff0e974 --- /dev/null +++ b/src/commands/types/generate/README.md @@ -0,0 +1,320 @@ +# Type Generation Command + +The Storyblok type generation command allows you to generate TypeScript type definitions for your Storyblok components. This is particularly useful for ensuring type safety when working with Storyblok content in your frontend applications. + +## Prerequisites + +Before generating types, ensure you have: + +- Access to the target Storyblok space +- Access to the target Storyblok space and proper permissions +- TypeScript installed in your project (if you plan to use the generated types) +- Pull components from the target space using the `storyblok components pull` command + +## Basic Usage + +```bash +# Generate types for all components in a space +storyblok types generate --space 12345 + +# Generate types with strict mode +storyblok types generate --space 12345 --strict + +# Generate types with a custom prefix for component names +storyblok types generate --space 12345 --type-prefix "Custom" + +# Generate types with a custom suffix for component names (if you used the same flag when pulling components) +storyblok types generate --space 12345 --suffix "Component" + +# Generate types in separate files (if you used the same flag when pulling components) +storyblok types generate --space 12345 --separate-files + +# Generate types with a custom fields parser +storyblok types generate --space 12345 --custom-fields-parser ./path/to/parser.ts + +# Generate types with custom compiler options +storyblok types generate --space 12345 --compiler-options ./path/to/options.json +``` + +## Architecture & Flow + +The type generation command is organized in three main layers with a specific processing flow to ensure accurate type generation. + +### Command Structure + +```typescript +// 1. Command Layer (index.ts) +typesCommand + .command('generate') + .option('--sf, --separate-files', 'Generate types in separate files') + .option('--strict', 'Use strict mode for type generation') + .option('--type-prefix ', 'Prefix to be prepended to all generated component type names') + .option('--suffix ', 'Components suffix') + .option('--custom-fields-parser ', 'Path to the parser file for Custom Field Types') + .option('--compiler-options ', 'Path to the compiler options from json-schema-to-typescript') + .action(async (options) => { + // Command implementation + }); + +// 2. Operations Layer (actions.ts) +-generateTypes() +- generateStoryblokTypes() +- saveTypesToFile() + +// 3. Actions Layer (actions.ts) +- getComponentType() +- getComponentPropertiesTypeAnnotations() +- sanitizeComponentName(); +``` + +### Processing Flow Examples + +#### 1. Basic Type Generation + +```bash +storyblok types generate --space 12345 +``` + +Flow: + +**Read Phase** +```typescript +// 1. Read components from space +const spaceData = await readComponentsFiles({ + from: '12345', + path: undefined +}); + +// 2. Generate Storyblok types +await generateStoryblokTypes({ + filename: undefined, + path: undefined +}); +``` + +**Generation Phase** +```typescript +// 3. Generate component types +const typedefString = await generateTypes(spaceData, { + // Default options +}); +``` + +**Save Phase** +```typescript +// 4. Save types to file +await saveTypesToFile('12345', typedefString, { + // Default options +}); +``` + +#### 2. Strict Mode Type Generation + +```bash +storyblok types generate --space 12345 --strict +``` + +Flow: + +**Generation Phase** +```typescript +// 1. Generate component types with strict mode +const typedefString = await generateTypes(spaceData, { + strict: true +}); +``` + +**Type Annotation Example** +```typescript +// Without strict mode (loose types) +export interface Component { + text?: string; + image?: { + filename: string; + alt: string; + }; + [k: string]: unknown; // Index signature for additional properties +} + +// With strict mode +export interface Component { + text?: string; + image?: { + filename: string; + alt: string; + }; + // No index signature, only explicitly defined properties are allowed +} +``` + +#### 3. Custom Type Prefix + +```bash +storyblok types generate --space 12345 --type-prefix "Custom" +``` + +Flow: + +**Component Type Generation** +```typescript +// 1. Get component type with prefix +const componentType = getComponentType(component.name, { + typePrefix: 'Custom' +}); + +// 2. Result: "CustomComponentName" instead of "ComponentName" +``` + +#### 4. Separate Files Generation + +```bash +storyblok types generate --space 12345 --separate-files +``` + +Flow: + +**File Generation** +```typescript +// 1. Generate types for each component +for (const component of spaceData.components) { + const componentType = getComponentType(component.name, options); + const properties = getComponentPropertiesTypeAnnotations(component.schema, options); + + // 2. Create a separate file for each component + const fileContent = `export interface ${componentType} { + ${properties} +}`; + + // 3. Save to a separate file + await saveToFile(`${component.name}.d.ts`, fileContent); +} +``` + +#### 5. Custom Fields Parser + +```bash +storyblok types generate --space 12345 --custom-fields-parser ./path/to/parser.ts +``` + +Flow: + +**Parser Loading** +```typescript +// 1. Load custom fields parser +const customFieldsParser = await import('./path/to/parser.ts'); + +// 2. Use parser for custom field types +const propertyType = customFieldsParser(property); +``` + +## Key Features + +### Type Safety + +- Generate TypeScript interfaces for all Storyblok components +- Ensure type safety when working with Storyblok content +- Reduce runtime errors by catching type issues at compile time + +### Customization Options + +- Add prefixes to component type names +- Add suffixes to component type names +- Generate types in separate files +- Use strict mode for more precise types +- Customize compiler options + +### Custom Field Support + +- Parse custom field types with a custom parser +- Extend type generation for non-standard field types +- Support for complex field structures + +### Storyblok Type Definitions + +- Generate type definitions for Storyblok's built-in field types +- Include type definitions for Storyblok's API responses +- Ensure complete type coverage for Storyblok integration + +## Type Generation File Structure + +Generated type files follow this structure: + +```typescript +// For a component named "hero" with text and image fields +export interface Hero { + text: string; + image: { + filename: string; + alt: string; + }; +} + +// For a component with nested bloks +export interface Page { + title: string; + sections: Array<{ + component: string; + _uid: string; + text?: string; + image?: { + filename: string; + alt: string; + }; + }>; +} +``` + +## Testing Strategy + +The command includes comprehensive test coverage: + +### Unit Tests + +- Component type generation +- Property type annotation generation +- Custom field parsing +- File saving functionality + +### Testing Checklist + +#### Running Type Generation + +**General** +- [ ] It should show the command title +- [ ] It should throw an error if the user is not logged in: "You are currently not logged in. Please login first to get your user info." + +**Required Arguments** +- `--space=TARGET_SPACE_ID` + - [ ] It should read components from the target space + - [ ] It should generate types for all components + - [ ] It should save the generated types to a file + +**Options** +- `--strict` + - [ ] It should generate strict types without the [k: string]: unknown index signature + - [ ] It should only allow explicitly defined properties + +- `--type-prefix=` + - [ ] It should prepend the prefix to all component type names + - [ ] It should handle special characters in the prefix + +- `--suffix=` + - [ ] It should append the suffix to all component type names + - [ ] It should handle special characters in the suffix + +- `--separate-files` + - [ ] It should generate a separate file for each component + - [ ] It should name files according to component names + +- `--custom-fields-parser=` + - [ ] It should load the custom fields parser from the specified path + - [ ] It should use the parser for custom field types + +- `--compiler-options=` + - [ ] It should load compiler options from the specified path + - [ ] It should apply the options to the type generation + +**Error Handling** +- [ ] It should throw an error if the space is not provided: "Please provide the space as argument --space YOUR_SPACE_ID." +- [ ] It should handle errors during type generation gracefully +- [ ] It should provide meaningful error messages for common issues