storyblok 3.28.1 → 3.29.1

package/README.md

@@ -554,6 +554,92 @@ module.exports = function (block) {
 }
 ```
 
+## Typescript
+It is possible to generate Typescript type definitions for your Storyblok components. The type definitions are based on the components' JSON Schema that can be retrieved with the [pull-components](#pull-components) command.
+
+### generate-typescript-typedefs
+
+Generate a file with the type definitions for the specified components' JSON Schemas.
+
+```sh
+$ storyblok generate-typescript-typedefs
+  --sourceFilePaths <PATHS>
+  --destinationFilePath <PATH>
+  --typeNamesPrefix <STRING>
+  --typeNamesSuffix <STRING>
+  --JSONSchemaToTSOptionsPath <PATH>
+  --customFieldTypesParserPath <PATH>
+```
+
+#### Options
+
+* `sourceFilePaths` <sub>(alias `source`)</sub> : Path(s) to the components JSON file(s) as comma separated values
+* `destinationFilePath` <sub>(alias `target`) *optional*</sub> : Path to the Typescript file that will be generated (*default*: `storyblok-component-types.d.ts`)
+* `typeNamesPrefix` <sub>(alias `titlePrefix`) *optional*</sub> : A prefix that will be prepended to all the names of the generated types
+* `typeNamesSuffix` <sub>(alias `titleSuffix`) *optional*</sub> : A suffix that will be appended to all the names of the generated types (*default*: `Storyblok`)
+* `JSONSchemaToTSOptionsPath` <sub>(alias `compilerOptions`) *optional*</sub> : Path to a JSON file with a list of options supported by `json-schema-to-typescript`
+* `customFieldTypesParserPath` <sub>(alias `customTypeParser`) *optional*</sub> : Path to the parser file for Custom Field Types
+
+#### Examples
+
+```sh
+# Generate typedefs for the components retrieved for the space `12345` via the `storyblok pull-components` command
+$ storyblok generate-typescript-typedefs --sourceFilePaths ./components.12345.json
+
+# Generate typedefs for multiple components sources
+$ storyblok generate-typescript-typedefs --sourceFilePaths ./fooComponent-12345.json,./barComponent-12345.json
+
+# Custom path for the typedefs file
+$ storyblok generate-typescript-typedefs --sourceFilePaths ./components.12345.json --destinationFilePath ./types/my-custom-type-file.d.ts
+
+# Provide customized options for the JSON-schema-to-typescript lib
+$ storyblok generate-typescript-typedefs --sourceFilePaths ./components.12345.json --JSONSchemaToTSOptionsPath ./PathToJSONFileWithCustomOptions.json
+
+# Provide a custom field types parser
+$ storyblok generate-typescript-typedefs --sourceFilePaths ./components.12345.json --customFieldTypesParserPath ./customFieldTypesParser.js
+
+```
+
+##### JSON Schema to Typescript options
+This script uses the `json-schema-to-typescript` library under the hood. Values of the [JSON Schema to Typescript options](https://www.npmjs.com/package/json-schema-to-typescript#options) can be customized providing a JSON file to the `JSONSchemaToTSOptionsPath`.
+
+The default values used for the `storyblok generate-typescript-typedefs` command are the same defaults for the library except for two properties:
+* `bannerComment` - The default value is `""` to remove noise from the generated Typedefs file
+* `unknownAny` - The default value is `false` because it can help a smoother Typescript adoption on a JS project
+
+Example `JSONSchemaToTSOptions` JSON file to remove `additionalProperties` from the generated type definitions:
+
+```json
+{
+  "additionalProperties": false,
+}
+```
+
+##### Custom Field Types parser
+Storyblok [Custom Field Types](https://www.storyblok.com/docs/plugins/field-plugins/introduction) do not have inherent JSONSchema definitions. To overcome this issue, you can provide a path to a script exporting a parser function that should render a [JSONSchema Node](https://json-schema.org/learn/getting-started-step-by-step#define-properties) for each of your Custom Field Types. The parser function should be exported as a default export, like in the following example:
+```js
+export default function (key, obj) {
+  switch (obj.field_type) {
+    case 'my-custom-field-type-name':
+      return {
+        [key]: {
+          type: 'object',
+          properties: {
+            color: { type: 'string' }
+          },
+          required: ['color']
+        }
+      }
+    default:
+      return {}
+  }
+}
+```
+
+
+
+
+
 ## You're looking for a headstart?
 
 Check out our guides for client side apps (VueJS, Angular, React, ...), static site (Jekyll, NuxtJs, ...), dynamic site examples (Node, PHP, Python, Laravel, ...) on our [Getting Started](https://www.storyblok.com/getting-started) page.

package/{src/tasks/templates/teaser.js → dist/chunks/teaser.mjs}

@@ -1,4 +1,4 @@
-module.exports = `<div class="quickstart__teaser">
+const teaser = `<div class="quickstart__teaser">
   <!--
   The _editable attribute makes the next
   DOM-element clickable so the sidebar can
@@ -22,4 +22,6 @@ module.exports = `<div class="quickstart__teaser">
         <!-- HINT: Try to change something and the browser window in Storyblok will automatically refresh. -->
     </h3>
   </div>
-</div>`
+</div>`;
+
+export { teaser as default };

package/dist/cli.d.mts

@@ -0,0 +1,69 @@
+import { Options, JSONSchema } from 'json-schema-to-typescript';
+export { ISbStoryData } from 'storyblok-js-client';
+
+type StoryblokProvidedPropertyType = "asset" | "multiasset" | "multilink" | "table" | "richtext";
+type ComponentPropertySchemaType = StoryblokProvidedPropertyType | "array" | "bloks" | "boolean" | "custom" | "datetime" | "image" | "markdown" | "number" | "option" | "options" | "text" | "textarea";
+type JSONSchemaToTSOptions = Partial<Options>;
+interface GenerateTypescriptTypedefsCLIOptions {
+    sourceFilePaths: string[];
+    destinationFilePath?: string;
+    typeNamesPrefix?: string;
+    typeNamesSuffix?: string;
+    customFieldTypesParserPath?: string;
+    JSONSchemaToTSOptionsPath?: string;
+}
+interface ComponentPropertySchemaOption {
+    _uid: string;
+    name: string;
+    value: string;
+}
+type ComponentPropertySchema = {
+    asset_link_type?: boolean;
+    component_group_whitelist?: string[];
+    component_whitelist?: string[];
+    email_link_type?: boolean;
+    exclude_empty_option?: boolean;
+    filter_content_type?: string[];
+    key: string;
+    options?: ComponentPropertySchemaOption[];
+    pos: number;
+    restrict_components?: boolean;
+    restrict_type?: "groups" | "";
+    source?: "internal" | "external" | "internal_stories" | "internal_languages";
+    type: ComponentPropertySchemaType;
+    use_uuid?: boolean;
+};
+type ComponentPropertyTypeAnnotation = {
+    tsType: string | string[];
+} | {
+    type: string | string[];
+    enum: string[];
+} | {
+    type: string | string[];
+} | {
+    type: "array";
+    items: {
+        type: string | string[];
+    };
+} | {
+    type: "array";
+    items: {
+        enum: string[];
+    };
+};
+type GenerateTSTypedefsFromComponentsJSONSchemasOptions = {
+    sourceFilePaths: string[];
+    destinationFilePath: string;
+    typeNamesPrefix?: string;
+    typeNamesSuffix?: string;
+    customFieldTypesParserPath?: string;
+    JSONSchemaToTSCustomOptions: JSONSchemaToTSOptions;
+};
+type CustomTypeParser = (_typeName: string, _schema: ComponentPropertySchema) => Record<string, any>;
+type GetStoryblokProvidedPropertyTypeSchemaFn = (title: string) => JSONSchema;
+type ComponentGroupsAndNamesObject = {
+    componentGroups: Map<string, Set<string>>;
+    componentNames: Set<string>;
+};
+
+export type { ComponentGroupsAndNamesObject, ComponentPropertySchema, ComponentPropertySchemaOption, ComponentPropertySchemaType, ComponentPropertyTypeAnnotation, CustomTypeParser, GenerateTSTypedefsFromComponentsJSONSchemasOptions, GenerateTypescriptTypedefsCLIOptions, GetStoryblokProvidedPropertyTypeSchemaFn, JSONSchemaToTSOptions, StoryblokProvidedPropertyType };

package/dist/cli.d.ts

@@ -0,0 +1,69 @@
+import { Options, JSONSchema } from 'json-schema-to-typescript';
+export { ISbStoryData } from 'storyblok-js-client';
+
+type StoryblokProvidedPropertyType = "asset" | "multiasset" | "multilink" | "table" | "richtext";
+type ComponentPropertySchemaType = StoryblokProvidedPropertyType | "array" | "bloks" | "boolean" | "custom" | "datetime" | "image" | "markdown" | "number" | "option" | "options" | "text" | "textarea";
+type JSONSchemaToTSOptions = Partial<Options>;
+interface GenerateTypescriptTypedefsCLIOptions {
+    sourceFilePaths: string[];
+    destinationFilePath?: string;
+    typeNamesPrefix?: string;
+    typeNamesSuffix?: string;
+    customFieldTypesParserPath?: string;
+    JSONSchemaToTSOptionsPath?: string;
+}
+interface ComponentPropertySchemaOption {
+    _uid: string;
+    name: string;
+    value: string;
+}
+type ComponentPropertySchema = {
+    asset_link_type?: boolean;
+    component_group_whitelist?: string[];
+    component_whitelist?: string[];
+    email_link_type?: boolean;
+    exclude_empty_option?: boolean;
+    filter_content_type?: string[];
+    key: string;
+    options?: ComponentPropertySchemaOption[];
+    pos: number;
+    restrict_components?: boolean;
+    restrict_type?: "groups" | "";
+    source?: "internal" | "external" | "internal_stories" | "internal_languages";
+    type: ComponentPropertySchemaType;
+    use_uuid?: boolean;
+};
+type ComponentPropertyTypeAnnotation = {
+    tsType: string | string[];
+} | {
+    type: string | string[];
+    enum: string[];
+} | {
+    type: string | string[];
+} | {
+    type: "array";
+    items: {
+        type: string | string[];
+    };
+} | {
+    type: "array";
+    items: {
+        enum: string[];
+    };
+};
+type GenerateTSTypedefsFromComponentsJSONSchemasOptions = {
+    sourceFilePaths: string[];
+    destinationFilePath: string;
+    typeNamesPrefix?: string;
+    typeNamesSuffix?: string;
+    customFieldTypesParserPath?: string;
+    JSONSchemaToTSCustomOptions: JSONSchemaToTSOptions;
+};
+type CustomTypeParser = (_typeName: string, _schema: ComponentPropertySchema) => Record<string, any>;
+type GetStoryblokProvidedPropertyTypeSchemaFn = (title: string) => JSONSchema;
+type ComponentGroupsAndNamesObject = {
+    componentGroups: Map<string, Set<string>>;
+    componentNames: Set<string>;
+};
+
+export type { ComponentGroupsAndNamesObject, ComponentPropertySchema, ComponentPropertySchemaOption, ComponentPropertySchemaType, ComponentPropertyTypeAnnotation, CustomTypeParser, GenerateTSTypedefsFromComponentsJSONSchemasOptions, GenerateTypescriptTypedefsCLIOptions, GetStoryblokProvidedPropertyTypeSchemaFn, JSONSchemaToTSOptions, StoryblokProvidedPropertyType };