@acryldev/create-blends 1.7.3 → 1.7.5
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 +2 -2
- package/docs/framework/README.md +1 -1
- package/docs/framework/cordis/migration-to-1-0.md +4 -4
- package/docs/framework/getting-started/basic.md +4 -4
- package/docs/framework/getting-started/bun.md +2 -2
- package/docs/framework/getting-started/nodejs.md +3 -3
- package/docs/framework/guides/create-acrylblends.md +5 -5
- package/docs/framework/helpers/streaming.md +1 -1
- package/docs/framework/workshop/README.md +3 -3
- package/docs/framework/workshop/facilitator.md +3 -3
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ Create an Acryl app with one command.
|
|
|
6
6
|
npm create @acryldev/blends@latest my-app
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
It asks which template you want, creates `my-app`, and prints what to run next. Other package managers work the same way: `pnpm create @acryldev/blends@latest`, `yarn create
|
|
9
|
+
It asks which template you want, creates `my-app`, and prints what to run next. Other package managers work the same way: `pnpm create @acryldev/blends@latest`, `yarn create @acryldev/blends`, `bun create @acryldev/blends`.
|
|
10
10
|
|
|
11
11
|
## Templates
|
|
12
12
|
|
|
@@ -102,4 +102,4 @@ npm create @acryldev/blends@latest my-app @scope/name[@version]
|
|
|
102
102
|
npm create @acryldev/blends@latest my-app ./template.tgz
|
|
103
103
|
```
|
|
104
104
|
|
|
105
|
-
The source is downloaded as a tarball (never cloned) or packed with `npm pack --ignore-scripts`, unpacked, and read: it must hold an `acryl.template.json` (`name`, `description`, optional `plugins`), it is checked for secrets, and only then is the folder created. Nothing of the template is installed or run; if its `package.json` defines install scripts they are listed, and `--install` prints what will run before it runs. See the create-
|
|
105
|
+
The source is downloaded as a tarball (never cloned) or packed with `npm pack --ignore-scripts`, unpacked, and read: it must hold an `acryl.template.json` (`name`, `description`, optional `plugins`), it is checked for secrets, and only then is the folder created. Nothing of the template is installed or run; if its `package.json` defines install scripts they are listed, and `--install` prints what will run before it runs. See the @acryldev/create-blends guide in `docs/framework/guides/`.
|
package/docs/framework/README.md
CHANGED
|
@@ -17,7 +17,7 @@ export default app
|
|
|
17
17
|
npm create @acryldev/blends@latest my-app
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
Other package managers work the same way: `pnpm create @acryldev/blends@latest`, `yarn create
|
|
20
|
+
Other package managers work the same way: `pnpm create @acryldev/blends@latest`, `yarn create @acryldev/blends`, `bun create @acryldev/blends`.
|
|
21
21
|
Every template is a Cordis app (`blend.yaml`, plugins in `plugins/`). The starter asks which one you want, from the same list `acrylblends init --template` takes: `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` (`acryl-app` is the old name for `agent`), and `npm create @acryldev/blends@latest my-app notes` names it directly. See [Getting started](getting-started/basic.md).
|
|
22
22
|
|
|
23
23
|
## What is in the box
|
|
@@ -7,12 +7,12 @@
|
|
|
7
7
|
An app made by `acrylblends init` carries copies of the framework plugins (`@acryldev/router`, `@acryldev/node-server`, `@acryldev/door`, `extensions`, ...) in `plugins/`. `acrylblends upgrade` brings them to the version of the installed package:
|
|
8
8
|
|
|
9
9
|
```sh
|
|
10
|
-
npx
|
|
11
|
-
npx
|
|
10
|
+
npx @acryldev/blends@latest upgrade --dry-run # what would change, and the diff of every file you edited
|
|
11
|
+
npx @acryldev/blends@latest upgrade # do it
|
|
12
12
|
npm install && npm run check && npm test
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
**Write `@latest`.** A bare `npx acrylblends upgrade` runs the `acrylblends` the app has installed, and an app made before 1.0 has a 0.x copy with no `upgrade` verb. It does not upgrade anything: depending on the platform and the version it prints its old help and exits 0 (so nothing happens and nothing says so), or answers "unknown command" and exits 2. `npx
|
|
15
|
+
**Write `@latest`.** A bare `npx acrylblends upgrade` runs the `acrylblends` the app has installed, and an app made before 1.0 has a 0.x copy with no `upgrade` verb. It does not upgrade anything: depending on the platform and the version it prints its old help and exits 0 (so nothing happens and nothing says so), or answers "unknown command" and exits 2. `npx @acryldev/blends@latest` fetches the current package and runs that. (After the first upgrade the app depends on 1.x, and the bare form works too.)
|
|
16
16
|
|
|
17
17
|
- A file nobody edited is replaced. A file the app edited stops the upgrade: nothing is changed, the diff of what would be lost is shown, and the command exits 1. Move your change out of the plugin (a plugin of your own in `plugins/<name>/` is never touched), or run `npx acrylblends upgrade --force`, which saves the edited versions in `.acryl/upgrade-backup/<time>/` before replacing them.
|
|
18
18
|
- `--diff` prints the diff of every changed file, not only the edited ones. `acrylblends upgrade @acryldev/router extensions` upgrades only those plugins.
|
|
@@ -31,7 +31,7 @@ npm install && npm run check && npm test
|
|
|
31
31
|
| The door (`door/*`, `cordis/door`), the agent panel and the PTY driver are experimental and development-only | They start nothing with `NODE_ENV=production` (the door plugin now checks it itself; `allowInProduction: true` for a host that means it); see [what runs in production](../guides/production.md) |
|
|
32
32
|
| `HTTPException` is `acrylblends/http-exception`, not the root | `import { HTTPException } from '@acryldev/blends/http-exception'` |
|
|
33
33
|
| `acrylblends/cordis/*` are the published forms of the framework plugins | In code that uses the package (not an app's own copies), import `acrylblends/cordis/router` where an old guide wrote `@acryldev/router` |
|
|
34
|
-
| One template list: `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` in both
|
|
34
|
+
| One template list: `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` in both `@acryldev/create-blends` and `acrylblends init` | `acryl-app` still means `agent` |
|
|
35
35
|
|
|
36
36
|
Node.js 22.19 or newer. Bun is optional and experimental; Deno is not supported.
|
|
37
37
|
|
|
@@ -5,7 +5,7 @@ which is experimental; only the entry point differs. This page shows the basic u
|
|
|
5
5
|
|
|
6
6
|
## Starter
|
|
7
7
|
|
|
8
|
-
A starter is a Cordis app that arrives already wired: `blend.yaml`, its plugins in `plugins/`, and a test. Use the
|
|
8
|
+
A starter is a Cordis app that arrives already wired: `blend.yaml`, its plugins in `plugins/`, and a test. Use the `npm create @acryldev/blends` command.
|
|
9
9
|
|
|
10
10
|
**npm**
|
|
11
11
|
|
|
@@ -16,7 +16,7 @@ npm create @acryldev/blends@latest my-app
|
|
|
16
16
|
**yarn**
|
|
17
17
|
|
|
18
18
|
```sh
|
|
19
|
-
yarn create
|
|
19
|
+
yarn create @acryldev/blends my-app
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
**pnpm**
|
|
@@ -28,7 +28,7 @@ pnpm create @acryldev/blends@latest my-app
|
|
|
28
28
|
**bun**
|
|
29
29
|
|
|
30
30
|
```sh
|
|
31
|
-
bun create
|
|
31
|
+
bun create @acryldev/blends my-app
|
|
32
32
|
```
|
|
33
33
|
|
|
34
34
|
You are asked which template you want:
|
|
@@ -45,7 +45,7 @@ Which template do you want to use? [nodejs]:
|
|
|
45
45
|
```
|
|
46
46
|
|
|
47
47
|
Every template is a Cordis app: `blend.yaml` lists its plugins and every plugin is a folder in `plugins/`. `blank` is the smallest app, `nodejs` is a web app with a page and a client component, `notes` and `chat` add a database, `todo` is a to-do list, and `agent` adds an agent that can extend the app while it
|
|
48
|
-
runs (see [Acryl in a Cordis app](../cordis/acryl-in-a-cordis-app.md)). Pass `--template` to skip the question, see [create-
|
|
48
|
+
runs (see [Acryl in a Cordis app](../cordis/acryl-in-a-cordis-app.md)). Pass `--template` to skip the question, see [@acryldev/create-blends](../guides/create-acrylblends.md).
|
|
49
49
|
|
|
50
50
|
The template is created in `my-app`: go to it, install the dependencies and start the local server.
|
|
51
51
|
|
|
@@ -18,7 +18,7 @@ A starter for Bun is available. Start your project with "bun create" command.
|
|
|
18
18
|
Select `bun` template for this example.
|
|
19
19
|
|
|
20
20
|
```sh
|
|
21
|
-
bun create
|
|
21
|
+
bun create @acryldev/blends my-app
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
Move into my-app and install the dependencies.
|
|
@@ -46,7 +46,7 @@ Then add the `dev` command to your existing `package.json`.
|
|
|
46
46
|
}
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
See the Bun starter template for a minimal example setup. This is the output of running `bun create
|
|
49
|
+
See the Bun starter template for a minimal example setup. This is the output of running `bun create @acryldev/blends`.
|
|
50
50
|
|
|
51
51
|
## 3. Hello World
|
|
52
52
|
|
|
@@ -9,7 +9,7 @@ On Node.js, Acryl runs through the Node.js adapter, `acrylblends/node-server`.
|
|
|
9
9
|
## 1. Setup
|
|
10
10
|
|
|
11
11
|
A starter for Node.js is available.
|
|
12
|
-
Start your project with
|
|
12
|
+
Start your project with the `npm create @acryldev/blends` command.
|
|
13
13
|
Select `nodejs` template for this example.
|
|
14
14
|
|
|
15
15
|
**npm**
|
|
@@ -21,7 +21,7 @@ npm create @acryldev/blends@latest my-app
|
|
|
21
21
|
**yarn**
|
|
22
22
|
|
|
23
23
|
```sh
|
|
24
|
-
yarn create
|
|
24
|
+
yarn create @acryldev/blends my-app
|
|
25
25
|
```
|
|
26
26
|
|
|
27
27
|
**pnpm**
|
|
@@ -33,7 +33,7 @@ pnpm create @acryldev/blends my-app
|
|
|
33
33
|
**bun**
|
|
34
34
|
|
|
35
35
|
```sh
|
|
36
|
-
bun create
|
|
36
|
+
bun create @acryldev/blends my-app
|
|
37
37
|
```
|
|
38
38
|
|
|
39
39
|
Move to `my-app` and install the dependencies.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
# create-
|
|
1
|
+
# @acryldev/create-blends
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
`yarn create
|
|
3
|
+
`@acryldev/create-blends` is the project initializer that runs when you run `npm create @acryldev/blends@latest`, `npx @acryldev/create-blends@latest`, `pnpm create @acryldev/blends@latest`,
|
|
4
|
+
`yarn create @acryldev/blends` or `bun create @acryldev/blends`. It creates a folder with a working Acryl application for the runtime you choose.
|
|
5
5
|
|
|
6
6
|
## Templates
|
|
7
7
|
|
|
@@ -32,7 +32,7 @@ npm create @acryldev/blends@latest my-app -- --template nodejs
|
|
|
32
32
|
**yarn**
|
|
33
33
|
|
|
34
34
|
```sh
|
|
35
|
-
yarn create
|
|
35
|
+
yarn create @acryldev/blends my-app --template nodejs
|
|
36
36
|
```
|
|
37
37
|
|
|
38
38
|
**pnpm**
|
|
@@ -44,7 +44,7 @@ pnpm create @acryldev/blends@latest my-app --template nodejs
|
|
|
44
44
|
**bun**
|
|
45
45
|
|
|
46
46
|
```sh
|
|
47
|
-
bun create
|
|
47
|
+
bun create @acryldev/blends my-app --template nodejs
|
|
48
48
|
```
|
|
49
49
|
|
|
50
50
|
## Arguments
|
|
@@ -184,7 +184,7 @@ for await (const { event, data } of readSSE(response)) {
|
|
|
184
184
|
- A response that is not `ok` throws with its status (the body is not parsed as events), and a response without a body throws.
|
|
185
185
|
- A client module served by `clientModules` can import it as it is (`import { readSSE } from '@acryldev/blends/read-sse'`): the import is pointed at a browser file the same app serves, like `acrylblends/client`. With a bundler it is an ordinary import.
|
|
186
186
|
|
|
187
|
-
A complete chat component is in the `chat` template of
|
|
187
|
+
A complete chat component is in the `chat` template of `@acryldev/create-blends` (`npm create @acryldev/blends@latest my-chat -- --template chat`).
|
|
188
188
|
|
|
189
189
|
## Error Handling
|
|
190
190
|
|
|
@@ -38,7 +38,7 @@ what is inside.
|
|
|
38
38
|
Run this first. It checks everything below and prints one line per check, with the exact command for anything missing:
|
|
39
39
|
|
|
40
40
|
```sh
|
|
41
|
-
npx
|
|
41
|
+
npx @acryldev/blends@latest preflight
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
It ends with `Ready for the workshop.`, or with how many lines say `FIX`: run each `FIX` line, then the preflight again. `NOTE` lines are things the
|
|
@@ -228,7 +228,7 @@ generated, plus the library plugins the app carries.
|
|
|
228
228
|
|
|
229
229
|
```sh
|
|
230
230
|
cd old-app
|
|
231
|
-
npx
|
|
231
|
+
npx @acryldev/blends@latest upgrade
|
|
232
232
|
npm install
|
|
233
233
|
npm run dev
|
|
234
234
|
```
|
|
@@ -280,7 +280,7 @@ the same folders. Nothing to install, nothing to keep on your machine. Until it
|
|
|
280
280
|
|
|
281
281
|
| Symptom | Do |
|
|
282
282
|
| --- | --- |
|
|
283
|
-
| The preflight prints `FIX` lines | run each one, then `npx
|
|
283
|
+
| The preflight prints `FIX` lines | run each one, then `npx @acryldev/blends@latest preflight` again |
|
|
284
284
|
| `npm create` fails or hangs | check the network; the facilitator has prepared apps |
|
|
285
285
|
| `npm install` fails building node-pty | install the C++ toolchain (block 1's **Stuck?**) and run it again |
|
|
286
286
|
| A port is taken | use the address the app printed |
|
|
@@ -6,13 +6,13 @@ chat model works on the app from inside the frame, and coding agents run in term
|
|
|
6
6
|
the panel-first flow of the previous handout are gone.
|
|
7
7
|
|
|
8
8
|
The handout is written for **acrylblends 1.3.0 or newer** (the release whose `create --desktop` makes the framed app). A room on an older release is on the previous handout;
|
|
9
|
-
check with `npx
|
|
9
|
+
check with `npx @acryldev/blends@latest --version` before the day.
|
|
10
10
|
|
|
11
11
|
## Before the room: put this on every machine
|
|
12
12
|
|
|
13
13
|
| What | Why | How |
|
|
14
14
|
| --- | --- | --- |
|
|
15
|
-
| The preflight passing | it checks Node, npm, git, an agent with its login or key, a free port, and on Windows PowerShell and long paths | `npx
|
|
15
|
+
| The preflight passing | it checks Node, npm, git, an agent with its login or key, a free port, and on Windows PowerShell and long paths | `npx @acryldev/blends@latest preflight` ends with `Ready for the workshop.` |
|
|
16
16
|
| Node.js 22.19 or newer (24 and 26 tested) | the app runs TypeScript directly | `node -v`; the app's `scripts/check-node.cjs` refuses an older Node with a clear line |
|
|
17
17
|
| git, and a GitHub account with `gh auth login` | the first `npm run dev` makes the folder a git repository (Files and Changes need one); the last block forks the registry | `git --version`, `gh auth status` |
|
|
18
18
|
| One coding agent, logged in | block 5 starts it in a terminal tab; `claude`, `codex` and `pi` all worked | `codex login` once, or run `claude` once, or pi with `DEEPSEEK_API_KEY` in the terminal that starts `npm run dev` |
|
|
@@ -39,7 +39,7 @@ run dev` (the terminal tabs inherit it); the preflight reports `PASS agent pi (D
|
|
|
39
39
|
| 25-30 | Settings > Models | the key saves with Apply (`Saved DeepSeek (deepseek-official).`); the page uses it after a reload | paste the key in the first-run card instead, Save and continue |
|
|
40
40
|
| 30-50 | chat builds the board | the chat writes into the app folder and Changes fills; the restart loop shows it at /app/board | if the model is slow, cut the board to one column |
|
|
41
41
|
| 50-65 | a coding agent in a terminal | the agent tab starts in the app folder (its prompt is `my-app`); `.acryl/bin/acryl look` prints the page in the frame's tile | demo one agent and let the room follow |
|
|
42
|
-
| 65-80 | upgrade an older app | `npx
|
|
42
|
+
| 65-80 | upgrade an older app | `npx @acryldev/blends@latest upgrade` reports every file it changed (the `frame` line is the new layout), then `npm install` and `npm run dev` | keep the report, skip the second app |
|
|
43
43
|
| 80-90 | publish (take-home) | the registry check merges in about two minutes | leave it as the take-home |
|
|
44
44
|
|
|
45
45
|
What the rehearsal verified end to end on this Mac: a packed CLI in an isolated HOME, the app opened by the frame with the app's page in a tab
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@acryldev/create-blends",
|
|
3
|
-
"version": "1.7.
|
|
3
|
+
"version": "1.7.5",
|
|
4
4
|
"description": "Create an Acryl app: npm create @acryldev/blends@latest",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
],
|
|
38
38
|
"dependencies": {
|
|
39
39
|
"@acryldev/app-persistence": "^0.1.3",
|
|
40
|
-
"@acryldev/blends": "^1.7.
|
|
40
|
+
"@acryldev/blends": "^1.7.5"
|
|
41
41
|
},
|
|
42
42
|
"publishConfig": {
|
|
43
43
|
"access": "public"
|