Skip to content
This repository was archived by the owner on Jan 19, 2026. It is now read-only.

chore: readme based on new template #183

Merged
alvarosabu merged 5 commits into from
May 5, 2025
Merged

chore: readme based on new template #183

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7581d40
docs: update README and add Type Generation Command documentation
alvarosabu May 5, 2025
2218ac8
docs: clean up README formatting and improve readability
alvarosabu May 5, 2025
e3719c3
docs: Update src/commands/types/generate/README.md
alvarosabu May 5, 2025
d387349
docs: Update src/commands/types/generate/README.md
alvarosabu May 5, 2025
4928072
docs: fix formatting in Type Generation Command section of README.md
alvarosabu May 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 63 additions & 86 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,118 +1,67 @@
![](/.github/assets/repo-banner.png)

<div align="center">
<h1>Storyblok CLI</h1>
<p align="center">A powerful CLI for scaffolding <a href="https://www.storyblok.com?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok" target="_blank">Storyblok</a> projects and fieldtypes.</p>

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

<h1>Storyblok CLI</h1>
<p>A powerful CLI tool to improve the DX of your <a href="https://www.storyblok.com?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok" target="_blank">Storyblok</a> projects.</p>
<br />
</div>

<p align="center">
<a href="https://npmjs.com/package/storyblok">
<img src="https://img.shields.io/npm/v/storyblok/latest.svg?style=flat-square" alt="Storyblok JS" />
<img src="https://img.shields.io/npm/v/storyblok/latest.svg?style=flat-square&color=8d60ff" alt="Storyblok JS Client" />
</a>
<a href="https://npmjs.com/package/storyblok" rel="nofollow">
<img src="https://img.shields.io/npm/dt/storyblok.svg?style=flat-square" alt="npm">
<img src="https://img.shields.io/npm/dt/storyblok.svg?style=appveyor&color=8d60ff" alt="npm">
</a>
</p>

<p align="center">
<a href="https://discord.gg/jKrbAMz">
<img src="https://img.shields.io/discord/700316478792138842?label=Join%20Our%20Discord%20Community&style=appveyor&logo=discord&color=09b3af">
<img src="https://img.shields.io/discord/700316478792138842?label=Join%20Our%20Discord%20Community&style=appveyor&logo=discord&color=8d60ff">
</a>
<a href="https://twitter.com/intent/follow?screen_name=storyblok">
<img src="https://img.shields.io/badge/Follow-%40storyblok-09b3af?style=appveyor&logo=twitter" alt="Follow @Storyblok" />
</a>
<a href="https://app.storyblok.com/#!/signup?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-richtext">
<img src="https://img.shields.io/badge/Try%20Storyblok-Free-09b3af?style=appveyor&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB4AAAAeCAYAAAA7MK6iAAAABGdBTUEAALGPC/xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAHqADAAQAAAABAAAAHgAAAADpiRU/AAACRElEQVRIDWNgGGmAEd3D3Js3LPrP8D8WXZwSPiMjw6qvPoHhyGYwIXNAbGpbCjbzP0MYuj0YFqMroBV/wCxmIeSju64eDNzMBJUxvP/9i2Hnq5cM1devMnz984eQsQwETeRhYWHgIcJiXqC6VHlFBjUeXgav40cIWkz1oLYXFmGwFBImaDFBHyObcOzdW4aSq5eRhRiE2dgYlpuYoYSKJi8vw3GgWnyAJIs/AuPu4scPGObd/fqVQZ+PHy7+6udPOBsXgySLDfn5GRYYmaKYJcXBgWLpsx8/GPa8foWiBhuHJIsl2DkYQqWksZkDFgP5PObcKYYff//iVAOTIDlx/QPqRMb/YSYBaWlOToZIaVkGZmAZSQiQ5OPtwHwacuo4iplMQEu6tXUZMhSUGDiYmBjylFQYvv/7x9B04xqKOnQOyT5GN+Df//8M59ASXKyMHLoyDD5JPtbj42OYrm+EYgg70JfuYuIoYmLs7AwMjIzA+uY/zjAnyWJpDk6GOFnCvrn86SOwmsNtKciVFAc1ileBHFDC67lzG10Yg0+SjzF0ownsf/OaofvOLYaDQJoQIGix94ljv1gIZI8Pv38zPvj2lQWYf3HGKbpDCFp85v07NnRN1OBTPY6JdRSGxcCw2k6sZuLVMZ5AV4s1TozPnGGFKbz+/PE7IJsHmC//MDMyhXBw8e6FyRFLv3Z0/IKuFqvFyIqAzd1PwBzJw8jAGPfVx38JshwlbIygxmYY43/GQmpais0ODDHuzevLMARHBcgIAQAbOJHZW0/EyQAAAABJRU5ErkJggg==" alt="Follow @Storyblok" />
<img src="https://img.shields.io/badge/Follow-%40storyblok-8d60ff?style=appveyor&logo=twitter" alt="Follow @Storyblok" />
</a><br/>
<a href="https://app.storyblok.com/#!/signup?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-cli">
<img src="https://img.shields.io/badge/Try%20Storyblok-Free-8d60ff?style=appveyor&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB4AAAAeCAYAAAA7MK6iAAAABGdBTUEAALGPC/xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAHqADAAQAAAABAAAAHgAAAADpiRU/AAACRElEQVRIDWNgGGmAEd3D3Js3LPrP8D8WXZwSPiMjw6qvPoHhyGYwIXNAbGpbCjbzP0MYuj0YFqMroBV/wCxmIeSju64eDNzMBJUxvP/9i2Hnq5cM1devMnz984eQsQwETeRhYWHgIcJiXqC6VHlFBjUeXgav40cIWkz1oLYXFmGwFBImaDFBHyObcOzdW4aSq5eRhRiE2dgYlpuYoYSKJi8vw3GgWnyAJIs/AuPu4scPGObd/fqVQZ+PHy7+6udPOBsXgySLDfn5GRYYmaKYJcXBgWLpsx8/GPa8foWiBhuHJIsl2DkYQqWksZkDFgP5PObcKYYff//iVAOTIDlx/QPqRMb/YSYBaWlOToZIaVkGZmAZSQiQ5OPtwHwacuo4iplMQEu6tXUZMhSUGDiYmBjylFQYvv/7x9B04xqKOnQOyT5GN+Df//8M59ASXKyMHLoyDD5JPtbj42OYrm+EYgg70JfuYuIoYmLs7AwMjIzA+uY/zjAnyWJpDk6GOFnCvrn86SOwmsNtKciVFAc1ileBHFDC67lzG10Yg0+SjzF0ownsf/OaofvOLYaDQJoQIGix94ljv1gIZI8Pv38zPvj2lQWYf3HGKbpDCFp85v07NnRN1OBTPY6JdRSGxcCw2k6sZuLVMZ5AV4s1TozPnGGFKbz+/PE7IJsHmC//MDMyhXBw8e6FyRFLv3Z0/IKuFqvFyIqAzd1PwBzJw8jAGPfVx38JshwlbIygxmYY43/GQmpais0ODDHuzevLMARHBcgIAQAbOJHZW0/EyQAAAABJRU5ErkJggg==" alt="Follow @Storyblok" />
</a>
</p>

## 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 <command>
```

## 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:

```
<filename>.<suffix>.<extension>
```
## Documentation

Where:

- `<filename>` is the name of the file. Customizable by the user with the `--filename` flag
- `<suffix>` 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
- `<extension>` 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 <command>
```

For example:
## Build

```bash
pnpm run dev login
pnpm build
```

### Testing
Expand Down Expand Up @@ -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)
Loading