generated from forge42dev/open-source-stack
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
7b3d8cb
commit 2de64f9
Showing
29 changed files
with
15,733 additions
and
13,230 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,55 +1,94 @@ | ||
| # Open-source stack | ||
| # Storyblok Generator | ||
|
|
||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
|
|
||
| Full starter stack to develop CJS/ESM compatible npm packages with TypeScript, Vitest, ESLint, Prettier, and GitHub Actions. | ||
| Storyblok React component generator for Vite Storyblok apps (React/Remix.run). | ||
|
|
||
| - Pulls in your components from Storyblok and generates the types for you. | ||
| - Generates the components in either a file or folder structure. | ||
| - Makes all components editable via the bridge by default. | ||
| - Adds per component bundle splitting for better performance. | ||
| - Adds full typesafety to your components. | ||
| - Supports both kebab-case and camel-case file names. | ||
| - Adds shortcuts to regenerate the components and types. | ||
|
|
||
| Deploy your open-source project to npm with ease, with fully covered bundling, testing, linting and deployment setup out of the box, | ||
| don't worry about CJS or ESM, bundling your typescript definitions or anything else, focus on coding out your solution and let the stack take care of the rest. | ||
| ## Setup | ||
|
|
||
| Build your own open-source project today! 🚀 | ||
| To get up and running quickly, you first install the vite plugin as a dev dependency in your project. | ||
|
|
||
| ## Tools | ||
| ```bash | ||
| npm install -D storyblok-generator | ||
| ``` | ||
|
|
||
| - **TypeScript**: TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. | ||
| - **Vitest**: A modern test runner built on top of Vite. | ||
| - **ESLint**: ESLint statically analyzes your code to quickly find problems. | ||
| - **Prettier**: Prettier is an opinionated code formatter. | ||
| - **GitHub Actions**: Automate your workflow from idea to production. | ||
| - **tsup** - Zero-config bundler for tiny TypeScript libraries. | ||
| Then, in your `vite.config.ts` file, add the following: | ||
|
|
||
| ## Features | ||
| ```typescript | ||
| import { storyblokPlugin } from "storyblok-generator" | ||
|
|
||
| - **ESM/CJS ready** - Write your code in TypeScript and publish it as ESM and CJS with 0 configuration. | ||
| - **Are The types wrong? ready** - Passes all the checks for typings on https://arethetypeswrong.github.io/ by default. | ||
| - **ESM/CJS test apps setup** - Test your package in both ESM and CJS environments already setup for you. | ||
| - **Test runner setup** - Test your open source package with Vitest already setup for you. | ||
| - **Linting setup** - Lint your code with ESLint and Prettier already setup for you. | ||
| - **GitHub Actions setup** - Automate deployments to npm by using GitHub Actions. | ||
| export default defineConfig({ | ||
| plugins: [ | ||
| storyblokPlugin({ | ||
| spaceId: "<your space id>", | ||
| componentsDir: "./storyblok/components", | ||
| }), | ||
| ], | ||
| }) | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| Once the plugin is installed and configured, it will generate the components and types for you. You can then import the components in your code and use them as you normally would. | ||
|
|
||
| ```typescript | ||
| import { components } from "./storyblok/components"; | ||
| import { storyblokInit, apiPlugin } from "@storyblok/react" | ||
|
|
||
| storyblokInit({ | ||
| accessToken: "<your access token>", | ||
| use: [apiPlugin], | ||
| // You pass in the components here, the components will be lazy loaded when actually used. | ||
| components, | ||
| }) | ||
| ``` | ||
|
|
||
| ### Storyblok CLI Caveats | ||
|
|
||
| The Plugin uses the Storyblok CLI to pull the components from your Storyblok space. This means that you need to have the CLI installed on your machine and available in your path. | ||
|
|
||
| You will also need to be logged in to the Storyblok CLI properly. You should login via SSO instead of | ||
| using the username and password combo as that keeps you logged in but after some time the login expires | ||
| and you need to login again by first logging out and logging in again. | ||
|
|
||
|
|
||
| ## Configuration | ||
|
|
||
| The plugin accepts the following configuration options: | ||
|
|
||
| | Option | Type | Description | Default | Required | | ||
| | ----------------- | -------- | --------------- | ------- | -------- | | ||
| | spaceId | string | Your Storyblok space ID. | - | Yes | | ||
| | componentsDir | string | The directory where the components will be generated. | - | Yes | | ||
| | typeFileLoc | string | The location of the type file. | `./storyblok/types.d.ts` | No | | ||
| | pullCommand | string | The command to use to pull the components from Storyblok via the CLI | `storyblok pull-components --space <spaceId> --path <pathToComponentsDir>` | No | | ||
| | typesCommand | string | The command to use to generate the types for the components via the CLI | `storyblok generate-typescript-typedefs --sourceFilePaths <pathToComponentsDir> --destinationFilePath <pathToTypeFileLoc>` | No | | ||
| | componentsJsonLoc | string | The location of the components JSON file. | `./storyblok/components.<spaceId>.json` | No | | ||
| | fileNameConvention | string | The file name convention for the components. Can be either `kebab-case` or `camel-case`. | `kebab-case` | No | | ||
| | componentAs | string | The component structure. Can be either `file` or `folder`. | `file` | No | | ||
| | debug | boolean | Whether to enable debug mode. If enabled, the plugin will print additional information to the console. | `false` | No | | ||
|
|
||
| ## Setup | ||
|
|
||
| 1. Use this template to create a new repository. | ||
| 2. Clone the repository. | ||
| 3. Change the package name in `package.json`. | ||
| 4. Change the `open-source-stack` dependency in your test-apps to your name | ||
| 5. Install the dependencies with `npm install`. | ||
| 6. Change the `repository`, `bugs`, and `homepage` fields in `package.json` to your github repo. | ||
| 7. Change the license if required. | ||
| 8. Add the NPM_TOKEN secret to your GitHub repository. | ||
| 9. Start coding! | ||
| ## Development | ||
|
|
||
| ## Scripts | ||
| To develop this plugin, you can clone the repository and run the following commands: | ||
|
|
||
| - `npm run build` - Build the package. | ||
| - `npm run test` - Run the tests. | ||
| - `npm run lint` - Lint the code. | ||
| - `npm run dev` - Start the package and ESM test app in watch mode for development. | ||
| - `npm run dev:cjs` - Start the package and CJS test app in watch mode for development. | ||
| ```bash | ||
| npm install | ||
| npm run dev | ||
| ``` | ||
|
|
||
| This will build the plugin, install the dependencies, and start the development server. |
Oops, something went wrong.