README
If you've found an issue or you have feature request - open an issue or look if it was already created.
3.x.x version released!
- completely rewritten to simple Meow lib with help of Typescript. Check migration guide
- support native es modules
- thinner then Oclif framework, still with Typescript
- decide to remove plugin support, cause it was not used enough
- make all commands follow same standard (
backup
command, had some very weird syntax before, now it works likesync
)
Contents
- How to install and configure
- NEW Adding Scoped Storyblok components
- NEW Overwriting schema files from scoped components
- Usage
- Schema documentation:
- Development
- Roadmap
How to install and configure
npm install --global sb-mig
You have to create a .env
file with your variables:
STORYBLOK_OAUTH_TOKEN=1234567890qwertyuiop
STORYBLOK_SPACE_ID=12345
STORYBLOK_ACCESS_TOKEN=zxcvbnmasdfghjkl
You can also provide your custom config. To do that u have to create storyblok.config.js
file in your root catalog with following structure:
// storyblok.config.js
module.exports = {
storyblokComponentsLocalDirectory: "src/@storyblok-components",
sbmigWorkingDirectory: "sbmig",
componentsDirectories: ["src", "storyblok"],
schemaFileExt: "sb.js",
datasourceExt: "sb.datasource.js",
rolesExt: "sb.roles.js",
storyblokApiUrl: "https://api.storyblok.com/v1",
oauthToken: process.env.STORYBLOK_OAUTH_TOKEN,
spaceId: process.env.STORYBLOK_SPACE_ID,
accessToken: process.env.STORYBLOK_ACCESS_TOKEN,
};
You don't need to pass everything to the config file, just add what you need and it will be merged with the original config. If you just need to set the componentDirectory
, for example, add the following:
// storyblok.config.js
module.exports = {
componentsDirectories: ["src", "storyblok", "@storyblok-components"],
};
Usage
$ sb-mig --help
CLI to rule the world. (and handle stuff related to Storyblok CMS)
USAGE
$ sb-mig [command]
COMMANDS
sync Synchronize components, datasources or roles with Storyblok space.
backup Command for backing up anything related to Storyblok
debug Output extra debugging information
help This screen
Examples
$ sb-migv sync components --all
$ sb-mig debug
Commands
sb-mig version
$ sb-mig --version
3.1.7
sb-mig backup
Command for backing up anything related to Storyblok
$ sb-mig backup --help
CLI to rule the world. (and handle stuff related to Storyblok CMS)
Usage
$ sb-mig-v3 backup [components|component-groups|roles|datasources|presets|component-presets] [space separated file names] or --all
Description
Command for backing up anything related to Storyblok
COMMANDS
components - backup components
component-groups - backuo component-groups
roles - backup components
datasources - backup components
presets - backup presets
component-presets - backup component presets
FLAGS
--all - Backup all
--one - Backup one
EXAMPLES
$ sb-mig backup components --all
$ sb-mig backup components accordion accordion-item carousel text-block
$ sb-mig backup datasources --all
$ sb-mig backup roles admin normal-user
sb-mig debug
Output extra debugging.
$ sb-mig debug
storyblok.config.js: {
componentsMatchFile: 'src/components/components.js',
storyblokComponentsListfile: 'src/components/storyblok-components.componentList.js',
storyblokComponentsLocalDirectory: 'src/@storyblok-components',
componentsStylesMatchFile: 'src/@storyblok-components/_storyblok-components.scss',
boilerplateUrl: 'git@github.com:storyblok-components/gatsby-storyblok-boilerplate.git',
sbmigWorkingDirectory: 'sbmig',
componentDirectory: 'storyblok',
datasourcesDirectory: 'storyblok',
componentsDirectories: [ 'src', 'storyblok' ],
schemaFileExt: 'sb.js',
datasourceExt: 'sb.datasource.js',
rolesExt: 'sb.roles.js',
storyblokApiUrl: 'https://api.storyblok.com/v1',
oauthToken: '',
spaceId: '',
accessToken: ''
}
sb-mig sync
Synchronize components, datasources or roles with Storyblok space.
$ sb-mig sync --help
CLI to rule the world. (and handle stuff related to Storyblok CMS)
Usage
$ sb-mig-v3 sync [components|roles|datasources] [space separated file names] or --all --packageName
Description
Synchronize components or roles with Storyblok space.
COMMANDS
components - sync components
roles - sync roles
datasources - sync datasources
FLAGS
--all - Sync all components
--packageName - Sync based on package name, instead of file name (package can have multiple schema files to sync)
--presets - Pass it, if u want to sync also with presets (will take longer)
EXAMPLES
$ sb-mig sync components --all
$ sb-mig sync components accordion accordion-item
$ sb-mig sync components @storyblok-components/accordion --packageName
Schema documentation:
Basics
This is what a basic storyblok .sb.js
schema file which maps to a component looks like:
expport default {
name: "text-block",
display_name: "Text block",
is_root: false,
is_nestable: true,
component_group_name: "Some group",
schema: {
title: {
type: "text",
},
}
};
Important notice: name inside .sb.js
schema need to match .sb.js
filename.
You can add anything mentioned here: https://www.storyblok.com/docs/api/management#core-resources/components/components to your component. (with the exception of component_group_uuid
: insert component_group_name
and sb-mig
will resolve uuid
automagically).
You can also add tabs
to your component schema (which is not documented in above storyblok documentation):
...
schema: {
title: {
type: "text",
},
Settings: {
type: "tab",
display_name: "Settings",
"keys": [
"title"
]
},
}
...
There is also support for sections
inside components:
...
schema: {
title: {
type: "text",
},
somesection: {
type: "section",
"keys": [
"title"
]
},
}
...
Syncing components
The main purpose of sb-mig
is to sync your .sb.js
component schema files with your Storyblok
space.
In v3.x.x There is 1 way to sync your schemas, which is to name all your schemas with .sb.js
extension. You can have them in any place of your repositories, as long as this place is pointed in storyblok.config.js
componentDirectories
field, which is set to componentsDirectories: ["src", "storyblok"],
by default:
sb-mig sync components row column
This command will look for row.sb.js
and column.sb.js
files inside a directories mentioned in componentDirectories
field. (You can change directories name mapping by modifying componentDirectories
inside storyblok.config.js
). You can also change the extension searched by changing schemaFileExt
. How to install and configure)
Syncing datasources
You can also sync your datasources
.
Add datasourceExt: "your-own-extension",
to your storyblok.config.js
. If u will not add it, will be used default one (sb.datasource.js
)
// storyblok.config.js
export default {
...
datasourcesDirectory: "mydatasource.ext.js"
...
};
Create file with .sb.datasource.js
(or your defined one) extension inside it. Basic schema for datasources file:
export default {
name: "icons",
slug: "icons",
datasource_entries: [
{
componentName: "icon1",
importPath: "icon 2"
},
{
componentName: "icon2",
importPath: "icon 2"
},
{
componentName: "icon3",
importPath: "icon 3"
},
{
componentName: "icon4",
importPath: "icon 4"
},
]
};
Above snippet will create datasource
with icons
name and icons
slug. datasource_entries
will be your name <-> value
array.
Single datasource entry
consist of precisely 2 fields. But they can be named however you like (advise to name it: name
and value
, it will be anyway translated to that, due to how storyblok stores them)
Command for syncing datasources:
sb-mig sync datasources icons
Example output from above command
Synciong priovided datasources icons...
Trying to sync provided datasources: icons
Trying to get all Datasources.
Trying to get 'icons' datasource entries.
Trying to get 'icons' datasource.
✓ Datasource entries for 15558 datasource id has been successfully synced
Like with syncing component, you can also use syncing multiple datasources at once:
sb-mig sync datasources icons logos
✓ Datasource entries for 15558 datasource id has been successfully synced.
✓ Datasource entries for 15559 datasource id has been successfully synced.
You can also sync all datasources, and that's the command we strongly recommend. It will sync all datasources also the one from node_modules, so potentially from storyblok-components
. But will prefer syncing local ones, if there will be clash of datasources filenames (for example, you can have datasource from node_modules, but wanted to overwrite some fields, you will be able to do that.
sb-mig sync datasources --all
Presets support
Writing your own predefined data (presets) for components can be a pain, so with sb-mig
you can create presets for your components in the storyblok gui, and then export them to a schema based .sb.js
file to be picked up while syncing.
To do so, first create a preset for your component in storyblok:
then run
sb-mig backup component-presets --one text-block // component you've created preset for
The tool will now download all presets related to the text-block
component.
Now you can go to your folder structure (by default: ./sbmig/component-presets/
), and rename the generated file to (for example): text-block-preset
.
You should remove the id field from the preset (it will be looked up by name)
Finally, add the all_presets
field to your text-block
component schema.
import allPresets from './presets/_text-block-preset.json'
export default {
...
schema: {
title: {
type: "text",
pos: 1
},
},
all_presets: allPresets,
...
};
Now, sync your component
sb-mig sync components --presets text-block
output:
Checking preset for 'text-block-2' component
Trying to get all 'text-block-2' presets.
Trying to get all components.
Trying to get preset by id: 437086
Preset: 'My Preset' with '437086' id has been updated.
This feature is still quite experimental, that's why it's not completely straightforward to do. Workin on it :)
Development
To develop and make changes to the library:
git clone git@github.com:sb-mig/sb-mig.git
Install packages
yarn
Link package to easy test it with sb-mig
command
yarn link
Roadmap
- Sync / Migrate content (stories)
- Improve preset creation/update
- Sync Roles
- Sync / Migrate datasources
- Sync components with extensions
- Sync presets
- Sync single component
- Sync all components
- Sync components using schema based .sb.js file (based on idea from storyblok-migrate)
- Component groups
- Sync custom fields
The general purpose of this package is to manage creation and maintenance of components from code/command line, to be able to create a whole space and project structure without using GUI.