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

Commit 8e37554

Browse files
alvarosabualvarosabu
committed
docs(components): add README files for components commands and update options
- Created detailed README files for the `components pull` and `components push` commands, outlining their usage, options, and examples for managing Storyblok components. - Updated the main README to reference the new `components` module and its subcommands, enhancing clarity for developers. - Adjusted option descriptions for consistency, including the removal of default values where applicable.
1 parent 24df207 commit 8e37554

7 files changed

Lines changed: 372 additions & 6 deletions

File tree

‎src/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ npm install storyblok@4.0.0-beta.<version>
2424
| [`logout`](./commands/logout/README.md) | ✅ Ready | |
2525
| [`user`](./commands/user/README.md) | ✅ Ready | |
2626
| [`languages pull`](./commands/languages/README.md) | ✅ Ready | Replaces previous pull-languages |
27-
| `components pull` | ✅ Ready | Replaces previous pull-components |
28-
| `components push` | ✅ Ready | Replaces previous push-components. Also handles dependencies such as groups, tags, presets and whitelists. (Datasources is pending) |
27+
| [`components pull`](./commands/components/pull/README.md) | ✅ Ready | Replaces previous pull-components |
28+
| [`components push`](./commands/components/push/README.md) | ✅ Ready | Replaces previous push-components. Also handles dependencies such as groups, tags, presets and whitelists. (Datasources is pending) |
2929
| `components delete` | 📝 Planned | Will replace delete-component and delete-components |
3030
| `migrations generate` | ✅ Ready | Replaces previous generate-migrations |
3131
| `migrations run` | ✅ Ready | Replaces previous run-migrations |

‎src/commands/components/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Components Command
2+
3+
The `components` module provides tools to manage Storyblok components and their dependencies.
4+
5+
## Subcommands
6+
7+
- [`pull`](./pull/README.md): Download components from your Storyblok space.
8+
- [`push`](./push/README.md): Upload components and their dependencies (groups, tags, presets, whitelists) to your Storyblok space.
9+
- `delete` (coming soon): Remove components from your Storyblok space.
10+
11+
> See each subcommand for detailed usage, options, and examples.

‎src/commands/components/pull/README.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Components Pull Command
2+
3+
The `components pull` command allows you to download components and their dependencies from your Storyblok space.
4+
5+
## Basic Usage
6+
7+
```bash
8+
storyblok components pull --space YOUR_SPACE_ID
9+
```
10+
11+
This will download all components and their dependencies to consolidated files:
12+
```
13+
.storyblok/
14+
└── components/
15+
└── YOUR_SPACE_ID/
16+
├── components.json # All components
17+
├── groups.json # Component groups
18+
├── presets.json # Component presets
19+
└── tags.json # Component tags
20+
```
21+
22+
> [!WARNING]
23+
> The `--filename` option is ignored when using `--separate-files`. Each component will be saved with its own name.
24+
25+
## Pull a Single Component
26+
27+
```bash
28+
storyblok components pull COMPONENT_NAME --space YOUR_SPACE_ID
29+
```
30+
31+
This will download a single component and its dependencies to:
32+
```
33+
.storyblok/
34+
└── components/
35+
└── YOUR_SPACE_ID/
36+
├── COMPONENT_NAME.json # Single component
37+
├── groups.json # Component groups
38+
├── COMPONENT_NAME.presets.json # Component presets
39+
└── tags.json # Component tags
40+
```
41+
42+
## Options
43+
44+
| Option | Description | Default |
45+
|--------|-------------|---------|
46+
| `-s, --space <space>` | (Required) The ID of the space to pull components from | - |
47+
| `-f, --filename <filename>` | Custom name for the components file | `components` |
48+
| `--sf, --separate-files` | Create a separate file for each component | `false` |
49+
| `--su, --suffix <suffix>` | Suffix to add to the files names | |
50+
| `-p, --path <path>` | Custom path to store the files | `.storyblok/components` |
51+
52+
## Examples
53+
54+
1. Pull all components with default settings:
55+
```bash
56+
storyblok components pull --space 12345
57+
```
58+
Generates:
59+
```
60+
.storyblok/
61+
└── components/
62+
└── 12345/
63+
├── components.json # All components
64+
├── groups.json # Component groups
65+
├── presets.json # Component presets
66+
└── tags.json # Component tags
67+
```
68+
69+
2. Pull a single component:
70+
```bash
71+
storyblok components pull hero --space 12345
72+
```
73+
Generates:
74+
```
75+
.storyblok/
76+
└── components/
77+
└── 12345/
78+
├── hero.json # Single component
79+
├── groups.json # Component groups
80+
├── hero.presets.json # Component presets
81+
└── tags.json # Component tags
82+
```
83+
84+
3. Pull components with custom filename:
85+
```bash
86+
storyblok components pull --space 12345 --filename my-components
87+
```
88+
Generates:
89+
```
90+
.storyblok/
91+
└── components/
92+
└── 12345/
93+
├── my-components.json # All components
94+
├── groups.json # Component groups
95+
├── presets.json # Component presets
96+
└── tags.json # Component tags
97+
```
98+
99+
4. Pull components with custom suffix:
100+
```bash
101+
storyblok components pull --space 12345 --suffix dev
102+
```
103+
Generates:
104+
```
105+
.storyblok/
106+
└── components/
107+
└── 12345/
108+
├── components.dev.json # All components
109+
├── groups.json # Component groups
110+
├── presets.json # Component presets
111+
└── tags.json # Component tags
112+
```
113+
114+
5. Pull components to separate files:
115+
```bash
116+
storyblok components pull --space 12345 --separate-files
117+
```
118+
Generates:
119+
```
120+
.storyblok/
121+
└── components/
122+
└── 12345/
123+
├── hero.json # Individual components
124+
├── hero.presets.json # Component presets
125+
├── feature.json
126+
├── feature.presets.json
127+
├── ...
128+
├── groups.json # Component groups
129+
└── tags.json # Component tags
130+
```
131+
132+
6. Pull components to a custom path:
133+
```bash
134+
storyblok components pull --space 12345 --path ./backup
135+
```
136+
Generates:
137+
```
138+
backup/
139+
└── components/
140+
└── 12345/
141+
├── components.json # All components
142+
├── groups.json # Component groups
143+
├── presets.json # Component presets
144+
└── tags.json # Component tags
145+
```
146+
147+
## File Structure
148+
149+
The command follows this pattern for file generation:
150+
```
151+
{path}/
152+
└── components/
153+
└── {spaceId}/
154+
├── {filename}.{suffix}.json # Components file
155+
├── groups.json # Component groups
156+
├── presets.json # Component presets
157+
└── tags.json # Component tags
158+
```
159+
160+
When using `--separate-files`:
161+
```
162+
{path}/
163+
└── components/
164+
└── {spaceId}/
165+
├── {componentName1}.json # Individual components
166+
├── {componentName1}.presets.json # Component presets
167+
├── {componentName2}.json
168+
├── {componentName2}.presets.json
169+
├── ...
170+
├── groups.json # Component groups
171+
└── tags.json # Component tags
172+
```
173+
174+
Where:
175+
- `{path}` is the base path (default: `.storyblok`)
176+
- `{spaceId}` is your Storyblok space ID
177+
- `{filename}` is the name you specified (default: `components`)
178+
- `{suffix}` is the suffix you specified (default: space ID)
179+
- `{componentName}` is the name of the component
180+
181+
## Notes
182+
183+
- You must be logged in to use this command
184+
- The space ID is required
185+
- The command will create the necessary directories if they don't exist
186+
- When using `--separate-files` or single component, presets are saved in separate files named `{componentName}.presets.json`
187+
- The command downloads:
188+
- Components
189+
- Component groups
190+
- Component presets
191+
- Component tags

‎src/commands/components/pull/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ const program = getProgram();
1414
componentsCommand
1515
.command('pull [componentName]')
1616
.option('-f, --filename <filename>', 'custom name to be used in file(s) name instead of space id')
17-
.option('--sf, --separate-files [value]', 'Argument to create a single file for each component')
17+
.option('--sf, --separate-files', 'Argument to create a single file for each component')
1818
.option('--su, --suffix <suffix>', 'suffix to add to the file name (e.g. components.<suffix>.json)')
1919
.description(`Download your space's components schema as json. Optionally specify a component name to pull a single component.`)
2020
.action(async (componentName: string | undefined, options: PullComponentsOptions) => {

‎src/commands/components/push/README.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Components Push Command
2+
3+
The `components push` command allows you to upload components and their dependencies to your Storyblok space.
4+
5+
> [!WARNING]
6+
> This command requires that you have previously used the `components pull` command to download the components. If you used any options during the pull (like `--suffix` or `--separate-files`), you must use the same options when pushing to ensure the files are found correctly.
7+
8+
## Basic Usage
9+
10+
```bash
11+
storyblok components push --space YOUR_SPACE_ID
12+
```
13+
14+
This will upload all components and their dependencies from:
15+
```
16+
.storyblok/
17+
└── components/
18+
└── YOUR_SPACE_ID/
19+
├── components.json # All components
20+
```
21+
22+
## Push a Single Component
23+
24+
```bash
25+
storyblok components push COMPONENT_NAME --space YOUR_SPACE_ID
26+
```
27+
28+
This will upload a single component and its dependencies from:
29+
```
30+
.storyblok/
31+
└── components/
32+
└── YOUR_SPACE_ID/
33+
├── COMPONENT_NAME.json # Single component
34+
```
35+
36+
## Options
37+
38+
| Option | Description | Default |
39+
|--------|-------------|---------|
40+
| `-s, --space <space>` | (Required) The ID of the space to push components to | - |
41+
| `-f, --from <from>` | Source space ID to read components from | Target space ID |
42+
| `--fi, --filter <filter>` | Glob pattern to filter components by their name (e.g., "hero*" will match all components starting with "hero") | - |
43+
| `--sf, --separate-files` | Read from separate files instead of consolidated files | `false` |
44+
| `--su, --suffix <suffix>` | Suffix to add to the files names | - |
45+
| `-p, --path <path>` | Custom path to read the files from | `.storyblok/components` |
46+
47+
## Examples
48+
49+
1. Push all components with default settings:
50+
```bash
51+
storyblok components push --space 12345
52+
```
53+
Reads from:
54+
```
55+
.storyblok/
56+
└── components/
57+
└── 12345/
58+
├── components.json # All components
59+
```
60+
61+
2. Push a single component:
62+
```bash
63+
storyblok components push hero --space 12345
64+
```
65+
Reads from:
66+
```
67+
.storyblok/
68+
└── components/
69+
└── 12345/
70+
├── hero.json # Single component
71+
```
72+
73+
3. Push components with filter:
74+
```bash
75+
storyblok components push --space 12345 --filter "hero*"
76+
```
77+
Reads from:
78+
```
79+
.storyblok/
80+
└── components/
81+
└── 12345/
82+
├── components.json # All components
83+
```
84+
85+
4. Push components from a different space:
86+
```bash
87+
storyblok components push --space 12345 --from 67890
88+
```
89+
Reads from:
90+
```
91+
.storyblok/
92+
└── components/
93+
└── 67890/
94+
├── components.json # All components
95+
```
96+
97+
5. Push components from separate files:
98+
```bash
99+
storyblok components push --space 12345 --separate-files
100+
```
101+
Reads from:
102+
```
103+
.storyblok/
104+
└── components/
105+
└── 12345/
106+
├── hero.json # Individual components
107+
├── hero.presets.json # Component presets
108+
├── feature.json
109+
├── feature.presets.json
110+
├── ...
111+
```
112+
113+
6. Push components from a custom path:
114+
```bash
115+
storyblok components push --space 12345 --path ./backup
116+
```
117+
Reads from:
118+
```
119+
backup/
120+
└── components/
121+
└── 12345/
122+
├── components.json # All components
123+
```
124+
125+
## File Structure
126+
127+
The command reads from the following file structure:
128+
```
129+
{path}/
130+
└── components/
131+
└── {spaceId}/
132+
├── components.{suffix}.json # Components file
133+
```
134+
135+
When using `--separate-files`:
136+
```
137+
{path}/
138+
└── components/
139+
└── {spaceId}/
140+
├── {componentName1}.{suffix}.json # Individual components
141+
├── {componentName1}.presets.json # Component presets
142+
├── {componentName2}.{suffix}.json
143+
├── {componentName2}.presets.json
144+
├── ...
145+
```
146+
147+
Where:
148+
- `{path}` is the base path (default: `.storyblok`)
149+
- `{spaceId}` is your Storyblok space ID
150+
- `{suffix}` is the suffix in the file name if provided
151+
- `{componentName}` is the name of the component
152+
153+
## Notes
154+
155+
- You must be logged in to use this command
156+
- The target space ID is required
157+
- The command will read from the specified path
158+
- When using `--separate-files` or single component, presets are read from separate files named `{componentName}.presets.json`
159+
- The command uploads:
160+
- Components
161+
- Component groups
162+
- Component presets
163+
- Component tags
164+
- Component whitelists

0 commit comments

Comments
 (0)