@anyday/sanity-workspace-manager 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +130 -31
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,51 +1,150 @@
|
|
|
1
1
|
# @anyday/sanity-workspace-manager
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
The command-line tool for Anyday's Sanity workspace manager. The workspace manager creates a new
|
|
4
|
+
Sanity workspace for a site in a few clicks: the project, its dataset, starter or copied content,
|
|
5
|
+
the brand, the central Studio entry and the Vercel site. It holds no code for any one project.
|
|
6
|
+
Each kind of site (a **project type**) is described instead by a `workspace-manager.json` manifest
|
|
7
|
+
that lives in that site's repo.
|
|
5
8
|
|
|
6
|
-
|
|
9
|
+
This tool writes and saves that manifest:
|
|
10
|
+
|
|
11
|
+
- **`init`** drafts `workspace-manager.json` from the site repo, its Sanity schema and, optionally,
|
|
12
|
+
the live Sanity project, then lists what it guessed so you can review it.
|
|
13
|
+
- **`register`** checks the manifest and saves it to the workspace manager, which then offers the
|
|
14
|
+
project type in the Workspaces app.
|
|
15
|
+
|
|
16
|
+
## Requirements
|
|
17
|
+
|
|
18
|
+
- Node.js 20 or later.
|
|
19
|
+
- A Sanity login: run `npx sanity login` once, or set `SANITY_AUTH_TOKEN`.
|
|
20
|
+
- For `register`, the **Administrator** role in the manifest's Sanity organisation.
|
|
21
|
+
|
|
22
|
+
## Quick start
|
|
23
|
+
|
|
24
|
+
From the root of the site repo:
|
|
7
25
|
|
|
8
26
|
```bash
|
|
9
|
-
#
|
|
10
|
-
npx sanity schema extract
|
|
27
|
+
# 1. Export the Studio's schema (writes sanity.schema.json)
|
|
28
|
+
cd studio && npx sanity schema extract && cd ..
|
|
11
29
|
|
|
12
|
-
#
|
|
13
|
-
npx @anyday/sanity-workspace-manager init
|
|
30
|
+
# 2. Draft the manifest, reading theme defaults and three starter pages from the live project
|
|
14
31
|
npx @anyday/sanity-workspace-manager init --live --starter home,about,contact
|
|
32
|
+
|
|
33
|
+
# 3. Review workspace-manager.json, then commit it next to the schema
|
|
34
|
+
|
|
35
|
+
# 4. Save it to the workspace manager
|
|
36
|
+
npx @anyday/sanity-workspace-manager register --api https://anyday-workspace-manager-sanity-api.vercel.app
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## init
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
npx @anyday/sanity-workspace-manager init [dir] [options]
|
|
15
43
|
```
|
|
16
44
|
|
|
17
|
-
|
|
45
|
+
`dir` is the site repo, and defaults to the current folder. `init` asks four questions, each with a
|
|
46
|
+
suggestion you can accept with Enter:
|
|
47
|
+
|
|
48
|
+
| Question | Suggested from |
|
|
49
|
+
| ------------------------------------------- | ------------------------------------------------------------------ |
|
|
50
|
+
| Project type id, short and lowercase | The repo name in the git remote, e.g. `acme-site` |
|
|
51
|
+
| Name shown in the app | The same repo name, capitalised |
|
|
52
|
+
| Sanity project to copy schemas from | A `projectId: '…'` written in the Studio's config, if there is one |
|
|
53
|
+
| Sanity organisation to create workspaces in | Looked up from that project with your login |
|
|
54
|
+
|
|
55
|
+
The id is permanent: jobs store it and it prefixes each site's Vercel project. Registering a
|
|
56
|
+
different id later creates a second project type instead of updating this one.
|
|
18
57
|
|
|
19
|
-
|
|
20
|
-
| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
21
|
-
| git remote and default branch | `site.repo`, `site.branch`, the suggested id and title |
|
|
22
|
-
| `.env.example` (names only) | `siteEnv` |
|
|
23
|
-
| `sanity.schema.json` | copy sections, singletons, home page, language documents, settings fields, colour and font templates |
|
|
24
|
-
| the live project (`--live`) | theme defaults, colour defaults, starter pages (`--starter <ids>`) |
|
|
58
|
+
### What it reads
|
|
25
59
|
|
|
26
|
-
|
|
27
|
-
|
|
60
|
+
| Source | Used for |
|
|
61
|
+
| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
62
|
+
| git remote and default branch | `site.repo`, `site.branch`, the suggested id and name |
|
|
63
|
+
| `.env.example`, names only | `siteEnv`, the variables each new site needs |
|
|
64
|
+
| `sanity.schema.json` | copy sections, singletons, home page, language documents, settings fields, colour and font templates |
|
|
65
|
+
| the live project, with `--live` | theme defaults, colour defaults and starter pages (`--starter <ids>`) |
|
|
28
66
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
67
|
+
`sanity.schema.json` is looked for in the repo root, `frontend`, `web`, `site`, `studio`, `apps`
|
|
68
|
+
and each folder in `apps`.
|
|
69
|
+
|
|
70
|
+
### Options
|
|
71
|
+
|
|
72
|
+
| Option | Does |
|
|
73
|
+
| ------------------ | --------------------------------------------------------------------------- |
|
|
74
|
+
| `--yes` | Accepts the suggested id, name and project without asking |
|
|
75
|
+
| `--project <id>` | The Sanity project new workspaces copy their schema from |
|
|
76
|
+
| `--org <id>` | The Sanity organisation new workspaces are created in (found with `--live`) |
|
|
77
|
+
| `--live` | Reads the current theme, settings and starter pages from that project |
|
|
78
|
+
| `--dataset <name>` | The dataset `--live` reads (default `production`) |
|
|
79
|
+
| `--starter <ids>` | Comma-separated document ids to use as starter content (needs `--live`) |
|
|
80
|
+
| `--force` | Replaces an existing `workspace-manager.json` |
|
|
81
|
+
| `--print` | Prints the draft instead of writing it |
|
|
82
|
+
|
|
83
|
+
Without `--starter`, new workspaces start from one empty home page. Starter pages get
|
|
84
|
+
`{{siteName}}` and `{{language}}` where the source site's name and language were. Font files are
|
|
85
|
+
never copied into theme defaults, since fonts are often licensed per brand.
|
|
86
|
+
|
|
87
|
+
### Review before registering
|
|
88
|
+
|
|
89
|
+
The draft is checked against the manifest's JSON Schema before it is written, and every guess is
|
|
90
|
+
listed afterwards. Check these in particular:
|
|
91
|
+
|
|
92
|
+
- **Copy sections** start as every content type. Keep only the ones editors should be able to copy
|
|
93
|
+
between workspaces.
|
|
94
|
+
- **Starter pages** must not link to documents outside the starter: a new workspace won't have
|
|
95
|
+
them, and saving the page fails. `init` names any such links.
|
|
96
|
+
- **Colour roles** come with empty descriptions. Add a short one each, saying where the colour is
|
|
97
|
+
used, so whoever sets up a brand knows what they are picking.
|
|
98
|
+
- **Language documents and singletons** are guessed from type names (`…Settings`, `l10n.locale`).
|
|
32
99
|
|
|
33
100
|
## register
|
|
34
101
|
|
|
35
102
|
```bash
|
|
36
|
-
|
|
37
|
-
npx @anyday/sanity-workspace-manager register --api https://anyday-workspace-manager-sanity-api.vercel.app
|
|
103
|
+
npx @anyday/sanity-workspace-manager register [dir] --api <url>
|
|
38
104
|
```
|
|
39
105
|
|
|
40
|
-
Checks
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
`
|
|
106
|
+
Checks `workspace-manager.json` in `dir` (default: the current folder) and saves it to the
|
|
107
|
+
workspace manager. The live API is `https://anyday-workspace-manager-sanity-api.vercel.app`; set
|
|
108
|
+
`WORKSPACE_MANAGER_API_URL` to skip `--api`.
|
|
109
|
+
|
|
110
|
+
- You must be an **Administrator** of the manifest's `organizationId`.
|
|
111
|
+
- Registering again replaces the saved copy for that `id`, so a changed manifest needs no delete
|
|
112
|
+
first.
|
|
113
|
+
- It prints `Registered <name> (<id>)` when saved.
|
|
114
|
+
|
|
115
|
+
## Signing in
|
|
116
|
+
|
|
117
|
+
Both commands use `SANITY_AUTH_TOKEN` when it is set, and otherwise the token `npx sanity login`
|
|
118
|
+
saved. Use your own login: the workspace manager refuses robot tokens for `register`, so that
|
|
119
|
+
every project type traces back to a person. If a robot token is exported in your shell (for
|
|
120
|
+
example for a Studio deploy), `unset SANITY_AUTH_TOKEN` before registering.
|
|
121
|
+
|
|
122
|
+
## Troubleshooting
|
|
123
|
+
|
|
124
|
+
| Message | Fix |
|
|
125
|
+
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
|
126
|
+
| `No sanity.schema.json` | Run `npx sanity schema extract` in the Studio folder |
|
|
127
|
+
| `workspace-manager.json exists: pass --force` | Add `--force` to replace it, or `--print` to compare |
|
|
128
|
+
| `--starter needs --live` | Add `--live`; starter pages are read from the live project |
|
|
129
|
+
| `Pass --api <url> or set WORKSPACE_MANAGER_API_URL` | Add `--api https://anyday-workspace-manager-sanity-api.vercel.app` |
|
|
130
|
+
| `Use your own Sanity login, not a robot token` | `unset SANITY_AUTH_TOKEN` and use `npx sanity login` |
|
|
131
|
+
| `Register only as an Administrator of organisation …` | Ask an Administrator of that organisation to run `register` |
|
|
132
|
+
|
|
133
|
+
## How it fits together
|
|
134
|
+
|
|
135
|
+
The full design, including every manifest field, is in
|
|
136
|
+
[docs/project-config.md](https://github.com/anydayagency/anyday-workspace-manager-sanity/blob/main/docs/project-config.md),
|
|
137
|
+
and an overview in
|
|
138
|
+
[docs/how-it-works.md](https://github.com/anydayagency/anyday-workspace-manager-sanity/blob/main/docs/how-it-works.md)
|
|
139
|
+
(Anyday's GitHub organisation only).
|
|
140
|
+
|
|
141
|
+
## Developing and publishing
|
|
45
142
|
|
|
46
|
-
|
|
143
|
+
From a clone of the workspace manager repo, run the CLI without npm:
|
|
144
|
+
`npm run cli -- init ../my-site`. `npm run build` bundles `src/cli.ts`, with the manifest code it
|
|
145
|
+
borrows from the API, into `dist/cli.mjs`; only `@sanity/client` and `ajv` stay dependencies.
|
|
47
146
|
|
|
48
|
-
|
|
49
|
-
`
|
|
50
|
-
|
|
51
|
-
|
|
147
|
+
Publish from `main`: bump `version`, then run
|
|
148
|
+
`npm publish --workspace=@anyday/sanity-workspace-manager --access public --auth-type=web` from the
|
|
149
|
+
repo root. It builds and tests first; the web sign-in covers npm's two-factor check, and the
|
|
150
|
+
release then waits for approval on npmjs.com.
|