@storyblok/field-plugin-cli NPM

Storyblok Field Plugin CLI

The Storyblok Field Plugin Command Line Interface provides functionality to create and deploy your field plugins in a much smoother and more intuitive way. To get started, use the following command:

Usage

In case no command is present the CLI will default to the create command.

npx @storyblok/field-plugin-cli@latest [command] [options]

Available options and commands:

Options:
  -V, --version     output the version number
  -h, --help        display help for command

Commands:
  create [options]  creates a new repository to start developing field plugins
  deploy [options]  deploys your selected plugin to Storyblok
  add    [options]  adds new field-plugin inside your project
  help   [command]  display help for command

create

The create command allows a set of optional options for customization.

--dir <value>         directory to create a repository into (default: `.`)
--pluginName <value>  name of plugin (Lowercase alphanumeric and dash)
--packageManager <value> package manager (choices: "npm", "yarn", "pnpm")
--repoName <value>    name of repository, for monorepo (Lowercase alphanumeric and dash)
--template <value>    name of template to use (choices: "vue2", "vue3", "react", "js")
--structure <value>   setup structure (choices: "standalone", "monorepo")
-h, --help            display help for command

Examples

# Run this simple command and you will be prompted to provide all required information
npx @storyblok/field-plugin-cli@latest

# Create a single field plugin with Vue 3 template inside a specific directory with a specific named
npx @storyblok/field-plugin-cli@latest create --dir=<PATH_TO_DIR> --pluginName=<FIELD_PLUGIN_NAME> --template=vue3 --structure=standalone --packageManager=npm

# Create a single field plugin with React template inside a specific directory with a specific named
npx @storyblok/field-plugin-cli@latest create --dir=<PATH_TO_DIR> --pluginName=<FIELD_PLUGIN_NAME> --template=react --structure=standalone --packageManager=npm

# Create a monorepo with field plugin with a specific named inside a specific directory with Vue 2 template
npx @storyblok/field-plugin-cli@latest create --dir=<PATH_TO_DIR> --pluginName=<FIELD_PLUGIN_NAME> --template=vue3 --structure=monorepo --packageManager=npm

Structure

Sometimes you might want to create only a single field plugin. At other times you might want to create and maintain multiple field plugins all in one repository. In both cases we have got you covered. The CLI supports both a standalone and a monorepo setup.

standalone (one package in one repo)

Here is a simplified folder structure of a standalone mode:

├── field-plugin
│   ├── src
│   ├── index.html
│   ├── package.json
│   ├── README.md
│   └── ...
└──

monorepo (multiple packages in one repo)

For a monorepo setup, we are using the following project structure:

├── field-plugins
│   ├── packages
│   │   ├── field-plugin
│   │   │   ├── src
│   │   │   ├── index.html
│   │   │   ├── package.json
│   │   │   ├── README.md
│   │   │   └── ...
│   │   └── ...
│   ├── README.md
│   └── package.json
└── ...

add

The options for the add command are the following:

--template <value>  name of template to use (choices: "vue2", "vue3", "react", "js")
--packageManager <value> package manager (choices: "npm", "yarn", "pnpm")
--name <value>      name of plugin (Lowercase alphanumeric and dash)
--dir <value>       directory to create a field plugin into (default: `.`)
-h, --help          display help for command

Examples

# Run this simple command and you will be prompted to provide all required information
npx @storyblok/field-plugin-cli@latest add

# Add field plugin with Vue 3 template to a project outside of the current directory
npx @storyblok/field-plugin-cli@latest add --name=<FIELD_PLUGIN_NAME> --template=vue3 --dir=<PATH_TO_DIR> --packageManager=npm

# Add field plugin with React template to a project outside of the current directory
npx @storyblok/field-plugin-cli@latest add --name=<FIELD_PLUGIN_NAME> --template=react --dir=<PATH_TO_DIR> --packageManager=npm

deploy

Uploading your field plugin implementation to Storyblok Partner Portal can be performed by simply running the deploy command.

:warning: A token to access the Storyblok Management API for upserting the field plugin must be provided. There are two ways how to pass a token to the CLI.
provide --token <STORYBLOK_PERSONAL_ACCESS_TOKEN> inside the deploy command
inside .env or .env.local create a new variable STORYBLOK_PERSONAL_ACCESS_TOKEN

For additional customizations you can add the following options to the command:

--token <value>       Storyblok personal access token
--skipPrompts         deploys without prompts (default: false)
--output <value>      defines location of the built output file
--dir <value>         path to field plugin to be deployed (default: ".")
-h, --help            display help for command

Examples

# Run this simple command and you will be prompted to provide all required information. NOTE: This command will work only if you have created STORYBLOK_PERSONAL_ACCESS_TOKEN as an environmental variable inside .env or .env.local!
npx @storyblok/field-plugin-cli@latest deploy

# Deploy your field plugin by providing a token
npx @storyblok/field-plugin-cli@latest deploy --token=<TOKEN>

# When used in a CI/CD one might want to skip the input prompts. This can be achieved with the --skipPrompts flag
npx @storyblok/field-plugin-cli@latest deploy --token=<TOKEN> --skipPrompts

# Deploy your field plugin from outside of the project
npx @storyblok/field-plugin-cli@latest deploy --token=<TOKEN> --dir=<PATH_TO_DIR>

:electric_plug: Installation

You can add the CLI to an existing field plugin project by running:

yarn add --dev @storyblok/field-plugin-cli@latest

In case you want to access the dependency globally use:

yarn global add @storyblok/field-plugin-cli@latest
# or
npm install @storyblok/field-plugin-cli@latest --global

:people_hugging: Supported Frameworks

We are working on providing templates for the popular frontend frameworks. Currently, our CLI includes templates created with:

React
Vue 3
Vue 2

:books: What's next?

Now that everything is set up you can go ahead and checkout Storyblok's resource on field plugins:

🔗 Field Plugin Documentation

🔗 Field Plugin Examples

🔗 Webinar Feature Focus: Field Plugin

:seedling: Contributing

Please see our contributing guidelines. We are always looking for feedback to create a better developer experience. If you happen to find a bug or simply would like to suggest a new feature, you can do so by submitting an issue.

When adding a new template to this repository, think of the following:

.gitignore files must be named gitignore. Otherwise, NPM will exclude the file from the release. The @storyblok/field-plugin-cli will automatically rename the file to .gitignore.
Add "deploy": "npm run build && npx @storyblok/field-plugin-cli@latest deploy" to the package.json