@acryldev/create-blends 1.7.0 → 1.7.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.
Files changed (98) hide show
  1. package/{docs/framework/LICENSE → LICENSE} +1 -3
  2. package/package.json +2 -2
  3. package/docs/framework/README.md +0 -70
  4. package/docs/framework/agents/index.md +0 -59
  5. package/docs/framework/api/acryl.md +0 -247
  6. package/docs/framework/api/context.md +0 -478
  7. package/docs/framework/api/exception.md +0 -80
  8. package/docs/framework/api/index.md +0 -12
  9. package/docs/framework/api/presets.md +0 -62
  10. package/docs/framework/api/request.md +0 -396
  11. package/docs/framework/api/routing.md +0 -303
  12. package/docs/framework/api/summary.md +0 -143
  13. package/docs/framework/concepts/benchmarks.md +0 -26
  14. package/docs/framework/concepts/developer-experience.md +0 -5
  15. package/docs/framework/concepts/middleware.md +0 -21
  16. package/docs/framework/concepts/motivation.md +0 -14
  17. package/docs/framework/concepts/routers.md +0 -63
  18. package/docs/framework/concepts/stacks.md +0 -235
  19. package/docs/framework/concepts/web-standard.md +0 -27
  20. package/docs/framework/cordis/acryl-in-a-cordis-app.md +0 -160
  21. package/docs/framework/cordis/concepts.md +0 -105
  22. package/docs/framework/cordis/middleware.md +0 -8
  23. package/docs/framework/cordis/migration-from-0-3.md +0 -111
  24. package/docs/framework/cordis/migration-from-0-4.md +0 -14
  25. package/docs/framework/cordis/migration-from-dsh-webserver.md +0 -109
  26. package/docs/framework/cordis/migration-to-1-0.md +0 -46
  27. package/docs/framework/cordis/mounting.md +0 -85
  28. package/docs/framework/cordis/node-server.md +0 -100
  29. package/docs/framework/cordis/plugin-lifecycle.md +0 -111
  30. package/docs/framework/cordis/surfaces.md +0 -71
  31. package/docs/framework/cordis/transport-and-cancellation.md +0 -57
  32. package/docs/framework/cordis/validation.md +0 -135
  33. package/docs/framework/getting-started/basic.md +0 -201
  34. package/docs/framework/getting-started/bun.md +0 -219
  35. package/docs/framework/getting-started/deploy.md +0 -133
  36. package/docs/framework/getting-started/desktop.md +0 -80
  37. package/docs/framework/getting-started/nodejs.md +0 -365
  38. package/docs/framework/getting-started/other-runtimes.md +0 -30
  39. package/docs/framework/guides/best-practices.md +0 -231
  40. package/docs/framework/guides/bring-your-own-tool.md +0 -218
  41. package/docs/framework/guides/client-modules.md +0 -210
  42. package/docs/framework/guides/create-acrylblends.md +0 -143
  43. package/docs/framework/guides/data.md +0 -314
  44. package/docs/framework/guides/examples.md +0 -3
  45. package/docs/framework/guides/faq.md +0 -19
  46. package/docs/framework/guides/forms-and-sessions.md +0 -235
  47. package/docs/framework/guides/helpers.md +0 -33
  48. package/docs/framework/guides/jsx-dom.md +0 -301
  49. package/docs/framework/guides/jsx.md +0 -487
  50. package/docs/framework/guides/middleware.md +0 -253
  51. package/docs/framework/guides/production.md +0 -80
  52. package/docs/framework/guides/rpc.md +0 -878
  53. package/docs/framework/guides/testing.md +0 -133
  54. package/docs/framework/guides/validation.md +0 -470
  55. package/docs/framework/helpers/accepts.md +0 -60
  56. package/docs/framework/helpers/adapter.md +0 -57
  57. package/docs/framework/helpers/conninfo.md +0 -77
  58. package/docs/framework/helpers/cookie.md +0 -232
  59. package/docs/framework/helpers/css.md +0 -282
  60. package/docs/framework/helpers/dev.md +0 -64
  61. package/docs/framework/helpers/factory.md +0 -180
  62. package/docs/framework/helpers/html.md +0 -123
  63. package/docs/framework/helpers/jwt.md +0 -184
  64. package/docs/framework/helpers/proxy.md +0 -115
  65. package/docs/framework/helpers/route.md +0 -143
  66. package/docs/framework/helpers/ssg.md +0 -390
  67. package/docs/framework/helpers/streaming.md +0 -224
  68. package/docs/framework/helpers/testing.md +0 -118
  69. package/docs/framework/helpers/websocket.md +0 -208
  70. package/docs/framework/middleware/builtin/basic-auth.md +0 -165
  71. package/docs/framework/middleware/builtin/bearer-auth.md +0 -138
  72. package/docs/framework/middleware/builtin/body-limit.md +0 -71
  73. package/docs/framework/middleware/builtin/cache.md +0 -99
  74. package/docs/framework/middleware/builtin/combine.md +0 -94
  75. package/docs/framework/middleware/builtin/compress.md +0 -59
  76. package/docs/framework/middleware/builtin/context-storage.md +0 -74
  77. package/docs/framework/middleware/builtin/cors.md +0 -134
  78. package/docs/framework/middleware/builtin/csrf.md +0 -105
  79. package/docs/framework/middleware/builtin/etag.md +0 -54
  80. package/docs/framework/middleware/builtin/ip-restriction.md +0 -69
  81. package/docs/framework/middleware/builtin/jsx-renderer.md +0 -283
  82. package/docs/framework/middleware/builtin/jwk.md +0 -192
  83. package/docs/framework/middleware/builtin/jwt.md +0 -145
  84. package/docs/framework/middleware/builtin/language.md +0 -232
  85. package/docs/framework/middleware/builtin/logger.md +0 -74
  86. package/docs/framework/middleware/builtin/loopback-only.md +0 -31
  87. package/docs/framework/middleware/builtin/method-not-allowed.md +0 -48
  88. package/docs/framework/middleware/builtin/method-override.md +0 -80
  89. package/docs/framework/middleware/builtin/mount.md +0 -103
  90. package/docs/framework/middleware/builtin/pretty-json.md +0 -53
  91. package/docs/framework/middleware/builtin/request-id.md +0 -87
  92. package/docs/framework/middleware/builtin/secure-headers.md +0 -247
  93. package/docs/framework/middleware/builtin/timeout.md +0 -98
  94. package/docs/framework/middleware/builtin/timing.md +0 -100
  95. package/docs/framework/middleware/builtin/trailing-slash.md +0 -74
  96. package/docs/framework/middleware/third-party.md +0 -4
  97. package/docs/framework/workshop/README.md +0 -294
  98. package/docs/framework/workshop/facilitator.md +0 -101
@@ -1,98 +0,0 @@
1
- # Timeout Middleware
2
-
3
- The Timeout Middleware enables you to easily manage request timeouts in your application. It allows you to set a maximum duration for requests and optionally define custom error responses if the specified timeout is exceeded.
4
-
5
- ## Import
6
-
7
- ```ts
8
- import { Acryl } from '@acryldev/blends'
9
- import { timeout } from '@acryldev/blends/timeout'
10
- ```
11
-
12
- ## Usage
13
-
14
- Here's how to use the Timeout Middleware with both default and custom settings:
15
-
16
- Default Settings:
17
-
18
- ```ts
19
- const app = new Acryl()
20
-
21
- // Applying a 5-second timeout
22
- app.use('/api', timeout(5000))
23
-
24
- // Handling a route
25
- app.get('/api/data', async (c) => {
26
- // Your route handler logic
27
- return c.json({ data: 'Your data here' })
28
- })
29
- ```
30
-
31
- Custom settings:
32
-
33
- ```ts
34
- import { HTTPException } from '@acryldev/blends/http-exception'
35
-
36
- // Custom exception factory function
37
- const customTimeoutException = (context) =>
38
- new HTTPException(408, {
39
- message: `Request timeout after waiting ${context.req.headers.get(
40
- 'Duration'
41
- )} seconds. Please try again later.`,
42
- })
43
-
44
- // for Static Exception Message
45
- // const customTimeoutException = new HTTPException(408, {
46
- // message: 'Operation timed out. Please try again later.'
47
- // });
48
-
49
- // Applying a 1-minute timeout with a custom exception
50
- app.use('/api/long-process', timeout(60000, customTimeoutException))
51
-
52
- app.get('/api/long-process', async (c) => {
53
- // Simulate a long process
54
- await new Promise((resolve) => setTimeout(resolve, 61000))
55
- return c.json({ data: 'This usually takes longer' })
56
- })
57
- ```
58
-
59
- ## Notes
60
-
61
- - The duration for the timeout can be specified in milliseconds. The middleware will automatically reject the promise and potentially throw an error if the specified duration is exceeded.
62
-
63
- - The timeout middleware cannot be used with stream Thus, use `stream.close` and `setTimeout` together.
64
-
65
- ```ts
66
- app.get('/sse', async (c) => {
67
- let id = 0
68
- let running = true
69
- let timer: number | undefined
70
-
71
- return streamSSE(c, async (stream) => {
72
- timer = setTimeout(() => {
73
- console.log('Stream timeout reached, closing stream')
74
- stream.close()
75
- }, 3000) as unknown as number
76
-
77
- stream.onAbort(async () => {
78
- console.log('Client closed connection')
79
- running = false
80
- clearTimeout(timer)
81
- })
82
-
83
- while (running) {
84
- const message = `It is ${new Date().toISOString()}`
85
- await stream.writeSSE({
86
- data: message,
87
- event: 'time-update',
88
- id: String(id++),
89
- })
90
- await stream.sleep(1000)
91
- }
92
- })
93
- })
94
- ```
95
-
96
- ## Middleware Conflicts
97
-
98
- Be cautious about the order of middleware, especially when using error-handling or other timing-related middleware, as it might affect the behavior of this timeout middleware.
@@ -1,100 +0,0 @@
1
- # Server-Timing Middleware
2
-
3
- The [Server-Timing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing) Middleware provides
4
- performance metrics in the response headers.
5
-
6
- > **Note.** The metrics come from timers around the handler, so they measure wall-clock time on the host the app runs on.
7
-
8
- ## Import
9
-
10
- **npm**
11
-
12
- ```ts
13
- import { Acryl } from '@acryldev/blends'
14
- import {
15
- timing,
16
- setMetric,
17
- startTime,
18
- endTime,
19
- wrapTime,
20
- } from '@acryldev/blends/timing'
21
- import type { TimingVariables } from '@acryldev/blends/timing'
22
- ```
23
-
24
- ## Usage
25
-
26
- ```js
27
- // Specify the variable types to infer the `c.get('metric')`:
28
- type Variables = TimingVariables
29
-
30
- const app = new Acryl<{ Variables: Variables }>()
31
-
32
- // add the middleware to your router
33
- app.use(timing());
34
-
35
- app.get('/', async (c) => {
36
-
37
- // add custom metrics
38
- setMetric(c, 'region', 'europe-west3')
39
-
40
- // add custom metrics with timing, must be in milliseconds
41
- setMetric(c, 'custom', 23.8, 'My custom Metric')
42
-
43
- // start a new timer
44
- startTime(c, 'db');
45
- const data = await db.findMany(...);
46
-
47
- // end the timer
48
- endTime(c, 'db');
49
-
50
- // ...or you can also just wrap a Promise using this function:
51
- const data = await wrapTime(c, 'db', db.findMany(...));
52
-
53
- return c.json({ response: data });
54
- });
55
- ```
56
-
57
- ### Conditionally enabled
58
-
59
- ```ts
60
- const app = new Acryl()
61
-
62
- app.use(
63
- '*',
64
- timing({
65
- // c: Context of the request
66
- enabled: (c) => c.req.method === 'POST',
67
- })
68
- )
69
- ```
70
-
71
- ## Result
72
-
73
- ## Options
74
-
75
- ### *(optional)* total: `boolean`
76
-
77
- Show the total response time. The default is `true`.
78
-
79
- ### *(optional)* enabled: `boolean` | `(c: Context) => boolean`
80
-
81
- Whether timings should be added to the headers or not. The default is `true`.
82
-
83
- ### *(optional)* totalDescription: `string`
84
-
85
- Description for the total response time. The default is `Total Response Time`.
86
-
87
- ### *(optional)* autoEnd: `boolean`
88
-
89
- If `startTime()` should end automatically at the end of the request.
90
- If disabled, not manually ended timers will not be shown.
91
-
92
- ### *(optional)* crossOrigin: `boolean` | `string` | `(c: Context) => boolean | string`
93
-
94
- The origin this timings header should be readable.
95
-
96
- - If false, only from current origin.
97
- - If true, from all origin.
98
- - If string, from this domain(s). Multiple domains must be separated with a comma.
99
-
100
- The default is `false`. See more [docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Timing-Allow-Origin).
@@ -1,74 +0,0 @@
1
- # Trailing Slash Middleware
2
-
3
- This middleware handles Trailing Slash in the URL on a GET request.
4
-
5
- `appendTrailingSlash` redirects the URL to which it added the Trailing Slash if the content was not found. Also, `trimTrailingSlash` will remove the Trailing Slash.
6
-
7
- ## Import
8
-
9
- ```ts
10
- import { Acryl } from '@acryldev/blends'
11
- import {
12
- appendTrailingSlash,
13
- trimTrailingSlash,
14
- } from '@acryldev/blends/trailing-slash'
15
- ```
16
-
17
- ## Usage
18
-
19
- Example of redirecting a GET request of `/about/me` to `/about/me/`.
20
-
21
- ```ts
22
- import { Acryl } from '@acryldev/blends'
23
- import { appendTrailingSlash } from '@acryldev/blends/trailing-slash'
24
-
25
- const app = new Acryl({ strict: true })
26
-
27
- app.use(appendTrailingSlash())
28
- app.get('/about/me/', (c) => c.text('With Trailing Slash'))
29
- ```
30
-
31
- Example of redirecting a GET request of `/about/me/` to `/about/me`.
32
-
33
- ```ts
34
- import { Acryl } from '@acryldev/blends'
35
- import { trimTrailingSlash } from '@acryldev/blends/trailing-slash'
36
-
37
- const app = new Acryl({ strict: true })
38
-
39
- app.use(trimTrailingSlash())
40
- app.get('/about/me', (c) => c.text('Without Trailing Slash'))
41
- ```
42
-
43
- ## Options
44
-
45
- ### *(optional)* alwaysRedirect: `boolean`
46
-
47
- By default, trailing slash middleware only redirects when the response status is `404`. When `alwaysRedirect` is set to `true`, the middleware redirects before executing handlers. This is useful for wildcard routes (`*`) where the default behavior doesn't work.
48
-
49
- ```ts
50
- const app = new Acryl()
51
-
52
- app.use(trimTrailingSlash({ alwaysRedirect: true }))
53
- app.get('/my-path/*', (c) => c.text('Wildcard route'))
54
- ```
55
-
56
- This option is available for both `trimTrailingSlash` and `appendTrailingSlash`.
57
-
58
- ### *(optional)* skip: `(path: string) => boolean`
59
-
60
- A function that determines whether the redirect should be skipped based on the request path. If the function returns `true`, the redirect will be skipped. This is useful when you want to exclude certain paths, such as those with file extensions, from being redirected.
61
-
62
- ```ts
63
- app.use(
64
- appendTrailingSlash({
65
- skip: (path) => /\.\w+$/.test(path),
66
- })
67
- )
68
- ```
69
-
70
- This option is available for both `trimTrailingSlash` and `appendTrailingSlash`.
71
-
72
- ## Note
73
-
74
- It will be enabled when the request method is `GET` and the response status is `404`.
@@ -1,4 +0,0 @@
1
- # Third-party Middleware
2
-
3
- > **Not yet available.** There is no registry of third-party middleware for Acryl yet. Middleware is an ordinary function `(c, next) => Promise<void>`, so any function that has
4
- > that shape works; see [Middleware](../concepts/middleware.md) and [Writing middleware](../guides/middleware.md).
@@ -1,294 +0,0 @@
1
- # Build your app inside the ACRYL frame: the ACRYL Blends workshop
2
-
3
- Ninety minutes, from an empty folder to an app that opens in ACRYL's own IDE: projects on the left, your app's page in the middle, files,
4
- changes, checks and terminals on the right, a chat model that works on your app beside it, and Claude, Codex or Pi running in terminal tabs in
5
- the same folder. **Acryl** is the small web framework underneath (a handler takes a `Request` and returns a `Response`); **ACRYL Blends** is the
6
- app around it: a folder of Cordis plugins with a `blend.yaml`, running on your machine, opened by the frame.
7
-
8
- The frame is the workshop's point. You do not edit a folder and alt-tab to a browser: your app is a page inside the workspace, the agents work in
9
- the same folder the frame shows, and every change you or an agent makes is one restart away from the page.
10
-
11
- This guide is for **acrylblends 1.3.0 or newer**; `npm create @acryldev/blends@latest` gives you that. An app you made with an older release gets the
12
- frame with the upgrade in block 6.
13
-
14
- ## The fastest start: ACRYL Control Center
15
-
16
- ACRYL Control Center lists your apps, makes new ones and starts them. Download it for your machine:
17
-
18
- | | Apple Silicon / ARM | Intel / x64 |
19
- | --- | --- | --- |
20
- | macOS | [ACRYL-Control-Center-mac-arm64.dmg](https://github.com/acrylblends/63-acryl-control-center/releases/latest/download/ACRYL-Control-Center-mac-arm64.dmg) | [ACRYL-Control-Center-mac-x64.dmg](https://github.com/acrylblends/63-acryl-control-center/releases/latest/download/ACRYL-Control-Center-mac-x64.dmg) |
21
- | Windows | [ACRYL-Control-Center-win-arm64.exe](https://github.com/acrylblends/63-acryl-control-center/releases/latest/download/ACRYL-Control-Center-win-arm64.exe) | [ACRYL-Control-Center-win-x64.exe](https://github.com/acrylblends/63-acryl-control-center/releases/latest/download/ACRYL-Control-Center-win-x64.exe) |
22
- | Linux (Debian, Ubuntu) | [ACRYL-Control-Center-linux-arm64.deb](https://github.com/acrylblends/63-acryl-control-center/releases/latest/download/ACRYL-Control-Center-linux-arm64.deb) | [ACRYL-Control-Center-linux-x64.deb](https://github.com/acrylblends/63-acryl-control-center/releases/latest/download/ACRYL-Control-Center-linux-x64.deb) |
23
-
24
- The apps are not signed yet: on macOS the first start is right-click > Open; on Windows SmartScreen may ask, More info > Run anyway; on Linux
25
- `sudo apt install ./ACRYL-Control-Center-linux-x64.deb`. Or, with Node.js installed, start it without a download:
26
-
27
- ```sh
28
- npx acryl --web # in your browser
29
- npx acryl --gui # in its own window
30
- ```
31
-
32
- Press **+ New app**, give it a name, pick a starter (Blank, Node.js, Notes, Chat, To-do, Agent) and Web or Desktop, then **Make it**: Control
33
- Center makes the app in `~/ACRYL/<name>`, installs it (about a minute) and starts it. The blocks below do the same with commands, and show
34
- what is inside.
35
-
36
- ## 0. Before you start (10 minutes)
37
-
38
- Run this first. It checks everything below and prints one line per check, with the exact command for anything missing:
39
-
40
- ```sh
41
- npx acrylblends@latest preflight
42
- ```
43
-
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
45
- first blocks do without.
46
-
47
- | | macOS | Windows | Linux |
48
- | --- | --- | --- | --- |
49
- | Node.js 22.19 or newer (24 and 26 work) | `node -v` | `node -v` | `node -v` |
50
- | git | `git --version` | `git --version` | `git --version` |
51
- | one coding agent, logged in | `codex login status` or `claude --version` or `pi --version` | same | same |
52
- | GitHub account and `gh`, for the last block | `gh auth status` | same | same |
53
-
54
- Install what is missing: Node from <https://nodejs.org> (the LTS), git from <https://git-scm.com>, the GitHub CLI from <https://cli.github.com> (`gh auth
55
- login` once), and one agent:
56
-
57
- - **Claude Code**: <https://claude.com/claude-code>, then run `claude` once to log in.
58
- - **Codex**: `npm i -g @openai/codex`, then `codex login`. If a run answers `model_not_found`, your account does not have the default model: pick one
59
- your account supports (`/model` inside codex, or `model = "..."` in `~/.codex/config.toml`).
60
- - **pi with DeepSeek**: `npm i -g @earendil-works/pi-coding-agent`, and set your DeepSeek key in the terminal you start the app from (the terminal
61
- tabs inherit that environment). The preflight checks the key: `PASS agent pi (DeepSeek key found)`.
62
-
63
- | macOS and Linux | Windows PowerShell | Windows cmd.exe |
64
- | --- | --- | --- |
65
- | `export DEEPSEEK_API_KEY=sk-...` | `$env:DEEPSEEK_API_KEY="sk-..."` | `set DEEPSEEK_API_KEY=sk-...` |
66
-
67
- **One model key for the chat.** The frame's chat needs a model: a DeepSeek API key from <https://platform.deepseek.com> is the shortest path (you add
68
- it in block 3). A Claude or ChatGPT subscription works too, through **Sign in with an account** on the same Settings page.
69
-
70
- No prior knowledge of ACRYL, Cordis or Blends is needed; every new word is explained where it appears.
71
-
72
- Make the workshop folder:
73
-
74
- | macOS and Linux | Windows PowerShell | Windows cmd.exe |
75
- | --- | --- | --- |
76
- | `mkdir ~/acryl-workshop && cd ~/acryl-workshop` | `mkdir ~/acryl-workshop` then `cd ~/acryl-workshop` | `mkdir %USERPROFILE%\acryl-workshop` then `cd %USERPROFILE%\acryl-workshop` |
77
-
78
- **On Windows.** Windows PowerShell 5.1 (the one Windows ships) has no `&&`: where this guide joins two commands with `&&`, type them as two lines, or join
79
- them with `;`. PowerShell 7 (`pwsh`) accepts `&&`. In cmd.exe, `Ctrl-C` asks `Terminate batch job (Y/N)?`: answer `Y`.
80
-
81
- **The agent setting that matters all day.** The agents are configured to act rather than to describe: when you ask for something, they write the
82
- files and check the result. If your agent stops to ask "shall I proceed?", answer "do it now" and it continues; that one sentence is the difference
83
- between watching and building.
84
-
85
- ## The path
86
-
87
- | Minutes | Block | What you get |
88
- | --- | --- | --- |
89
- | 0-10 | 0. Before you start | a checked machine, one model key, a folder |
90
- | 10-20 | 1. Create the app, open the frame | the app running and shown inside the ACRYL frame |
91
- | 20-25 | 2. Your first change | the app's page in the frame showing your edit |
92
- | 25-30 | 3. Connect your model in Settings > Models | a chat that answers |
93
- | 30-50 | 4. Chat: your model builds a page | a board page the model wrote and you saw at /app/board |
94
- | 50-65 | 5. A coding agent in a terminal tab | Claude, Codex or Pi working in the app's folder |
95
- | 65-80 | 6. Upgrade an older app onto the frame | an app from before today, opened by the frame |
96
- | 80-90 | 7. Publish it as a starter | the app listed in the workshop registry |
97
-
98
- > **Checkpoint 20 minutes:** the app's page is in the frame.
99
- > **Checkpoint 30 minutes:** the chat answers.
100
- > **Checkpoint 50 minutes:** the model's board is at /app/board.
101
- > **Checkpoint 65 minutes:** an agent in a terminal has changed the app.
102
-
103
- ## 1. Create the app; the frame opens on it (10 minutes)
104
-
105
- ```sh
106
- npm create @acryldev/blends@latest my-app agent -- --desktop
107
- cd my-app
108
- npm install
109
- npm run dev
110
- ```
111
-
112
- npm may warn that 5 packages have install scripts not covered by allowScripts; that is a notice, not an error - nothing to do.
113
-
114
- `npm install` is bigger than a framework-only app: it brings the frame and the chat engine (about 500 MB together, much less on a warm package
115
- cache). `npm run dev` starts the app inside the frame and prints one line:
116
-
117
- ```text
118
- acrylblends host: http://127.0.0.1:3489/?token=...
119
- ```
120
-
121
- Open that address (it is a free port on your machine; never a fixed one). It stays the same every time you start the app, and it is the way back in
122
- later: `npx acrylblends open` prints it again while the frame is running. The first time, DeepSeek Harness shows a **Preview Notice**: press **Continue**. Then the frame opens **on your app**: the page in the middle is `my-app`'s own page, in a tab named after the app.
123
-
124
- ![The frame on first run: projects on the left with the app selected, the app's page in the canvas, the tab strip with the app's tab](/docs-assets/workshop/s1-frame.webp)
125
-
126
- The three columns are ACRYL's IDE:
127
-
128
- - **Left:** your workspaces and projects. `my-app` is selected; the account row above and **Settings** below.
129
- - **Middle:** tabs. `my-app` is your app's page; the `+` at the left of the tab strip opens more (terminal, browser, files, chat, agents).
130
- - **Right:** open it with the panel button at the top right (or `Cmd/Ctrl+B`): **Files**, **Changes**, **Review**, **Checks**, **Comments** and a
131
- terminal. The bottom bar is the terminal dock.
132
-
133
- The app's page also has an agent of its own: **Ask the agent** at the bottom right opens the app's panel (the offline agent unless the app is given
134
- a model). The frame's chat in the next blocks is the tool you will use; the panel is there for the app to ship with.
135
-
136
- **Stuck?** A busy port means the terminal printed a different address; use that. `npm install` failing on the native terminal package needs a C++
137
- toolchain: on macOS `xcode-select --install`, on Windows the "Desktop development with C++" workload of Visual Studio Build Tools, on Ubuntu
138
- `sudo apt install build-essential python3`.
139
-
140
- ## 2. Your first change, seen at /app (5 minutes)
141
-
142
- Open the right panel (**Files**), expand `src`, click `routes.ts`. Find the sentence the page shows ("This app runs an agent unless it is switched
143
- off...") and change it to something that is yours. Press **Save** in the editor's bar (or `Cmd/Ctrl+S`).
144
-
145
- The running app does not pick a source change up by itself. Stop the host with `Ctrl-C` in the terminal where `npm run dev` runs (in cmd.exe answer
146
- `Y`), then start it again:
147
-
148
- ```sh
149
- npm run dev
150
- ```
151
-
152
- The frame reconnects on its own, on the same address (the port is stable per app), in a few seconds. If a chat tab opened in front, press the
153
- `my-app` tab: the page shows your sentence. That is the whole development loop for the rest of the day: edit, restart, look.
154
-
155
- ```sh
156
- npm test
157
- npm run check
158
- ```
159
-
160
- Both pass: the app is TypeScript, with tests and a type check, and the scaffold made the folder a git repository, so **Changes** shows what you
161
- edited.
162
-
163
- **Stuck?** If the page looks unchanged, the host did not restart (the terminal says `Restarting` or it is waiting on `Ctrl-C`). If the frame still
164
- says `Reconnecting...` after ten seconds, reload the tab: the address is the same one it was opened with. If the tab was closed, `npx acrylblends open`
165
- in the app's folder prints the address again.
166
-
167
- ## 3. Connect your model: Settings > Models (5 minutes)
168
-
169
- Press **Settings** at the bottom of the left column, then **Models** in its sidebar. The page lists DeepSeek as a provider: paste your API key into
170
- **API key** and press **Apply**. It answers `Saved DeepSeek (deepseek-official).`; the key goes to the frame's own credentials store, never into the
171
- app folder.
172
-
173
- ![Settings > Models with the DeepSeek key field](/docs-assets/workshop/s2-settings-models.webp)
174
-
175
- Then reload the frame (`Cmd/Ctrl+R`): the page you already had open picks the key up on its next load. A Claude or ChatGPT subscription instead of a
176
- key: **Sign in with an account** on the same page.
177
-
178
- If the frame greets you with DeepSeek Harness's **Add an API key to get started** card first, you can paste the key there and press **Save and
179
- continue**, or press **Configure later** and use Settings > Models; both write the same store.
180
-
181
- **Stuck?** "Loading the provider directory failed" means the host is not answering; start `npm run dev` again. A key that stays red is usually an
182
- extra space: paste it again.
183
-
184
- ## 4. Chat: your model works on the app (20 minutes)
185
-
186
- Press `+` at the left of the tab strip and choose **AcrylDSH Chat**; on the `my-app` row in the left pane, **New chat on my-app** does the same and
187
- binds the chat to the app's folder (the chat's workspace selector says `my-app`). Then ask, in one message:
188
-
189
- > Do it now, without asking for approval. Build a board page at /board in this app: three columns (backlog, doing, done) with cards that have a
190
- > checkbox to mark them done, a sidebar with filters (all, mine, done) and a count on each filter, a button that opens and closes the sidebar, and
191
- > a header button "New card" that adds one. Use the app's own state so the counts update live. Read AGENTS.md and the app's docs first. When you are
192
- > done, tell me what you changed.
193
-
194
- The chat writes into `my-app` (watch the **Changes** panel fill), and the app's page at `/app` shows it after the loop from block 2: `Ctrl-C`, `npm
195
- run dev`, the frame reconnects. The board is at `/app/board`: type the address in the app tab's bar (the same address with `/board` at the end) and
196
- press **Go**.
197
-
198
- ![The AcrylDSH Chat tab with the request, beside the app](/docs-assets/workshop/s3-chat.webp)
199
-
200
- Every model builds a slightly different board: yours may need a title typed before "New card" adds one, or keep the sidebar always open.
201
-
202
- **Stuck?** If the chat asks for a model, block 3 did not finish (or the page was not reloaded after Apply). If the model describes the plan and
203
- stops, reply "do it now, without asking for approval".
204
-
205
- ## 5. A coding agent in a terminal tab (15 minutes)
206
-
207
- Press `+` and choose **Claude**, **Codex** or **Pi** (or **New Terminal** and type the command yourself). The tab starts the agent in the app's
208
- folder: the terminal's prompt is `my-app`, and `pwd` prints the folder. Ask it, in the terminal:
209
-
210
- > Do it now, without asking for approval. Add a GET /time route that returns the current time as JSON, and a line on the app's page that shows it.
211
- > Then check it at http://127.0.0.1:3489/app/time.
212
-
213
- The port in that address is the one the frame printed. The agent edits the files, and the same loop shows them: `Ctrl-C`, `npm run dev`, the frame
214
- reconnects, the `my-app` tab.
215
-
216
- An agent that works in this folder can also use the app's **door**, the page channel the app carries in development: `.acryl/bin/acryl look` prints
217
- what is on the page with refs, and `act` clicks, types, selects, presses, scrolls, waits, navigates and reloads. Ask the terminal agent to look at
218
- the page before it tells you it is done; the app's own docs (`AGENTS.md`, `plugins/door`) say how.
219
-
220
- **Stuck?** An agent that says the terminal is not a TTY needs the tab, not a script. If the agent cannot log in, sign in in a terminal first
221
- (`claude`, `codex login`, pi with `DEEPSEEK_API_KEY`), then open the tab again.
222
-
223
- ## 6. Upgrade an older app onto the frame (10 minutes)
224
-
225
- An app made with an older acrylblends runs the framework only. The current release moves it onto the frame-hosted layout: the generated launcher,
226
- the frame's row and the app's plugins beside it, the mount config. **Your source stays yours**: the upgrade only touches the files acrylblends
227
- generated, plus the library plugins the app carries.
228
-
229
- ```sh
230
- cd old-app
231
- npx acrylblends@latest upgrade
232
- npm install
233
- npm run dev
234
- ```
235
-
236
- The report names every file it changed and ends with a `frame` line (for an app that already has the frame: `everything is up to date`). An app made
237
- today answers "everything is up to date" too. An app from a release **before 0.7.8** cannot start at all (its `src/main.ts` imports a `plugins/`
238
- folder that release did not write); the upgrade says so instead of touching it.
239
-
240
- **Stuck?** "is not the previous release's scaffold" means you edited a generated file: run with `--diff` to see it, save your version aside, and
241
- run again (or `--force`; the app's versions are backed up under `.acryl/upgrade-backup/`).
242
-
243
- ## 7. Publish it as a starter (10 minutes, take-home)
244
-
245
- Your app already is a starter: `blend.yaml` names it, `plugins/` holds its code.
246
-
247
- ```sh
248
- cd ~/acryl-workshop
249
- gh repo fork acryldev/workshop-2026-11-20 --clone
250
- cd workshop-2026-11-20
251
- node scripts/make-entry.mjs ../my-app <your-github-login>.my-app --description "the board my agent built"
252
- git add blends && git commit -m "add <your-github-login>.my-app"
253
- git push
254
- gh pr create --fill --repo acryldev/workshop-2026-11-20
255
- ```
256
-
257
- (On Windows PowerShell 5.1, `cd ~/acryl-workshop` works as written; in cmd.exe use `cd %USERPROFILE%\acryl-workshop`. Type the `git add` and `git
258
- commit` as two lines, or join them with `;`.)
259
-
260
- A check runs on the pull request and merges it: your starter is listed in about two minutes, and anyone can start from it with
261
- `npm create @acryldev/blends@latest another-app -- --from <your-github-login>.my-app --registry github:acryldev/workshop-2026-11-20`.
262
-
263
- **Stuck?** The registry's check comments what to change; fix, commit, push again. `gh auth status` not logged in means `gh auth login`.
264
-
265
- ## Browser only (WebBoxes.ai) TODO(M9)
266
-
267
- No local install? The same app, and the same agents working on it, will run as a hosted workspace: open it in a browser, pick a starter, and work in
268
- the same folders. Nothing to install, nothing to keep on your machine. Until it is live this section is a stub.
269
-
270
- ## Where next
271
-
272
- - **Read the docs you already have**: every app carries `docs/framework`, the same pages as <https://acrylblends.github.io/docs>.
273
- - **Teach the agents your app**: `AGENTS.md` is what they read first; add your team's conventions there and they follow them in the next run.
274
- - **Swap a provider by editing one row**: SQLite to Postgres, the browser to a window, one agent to another in the frame's agent list.
275
- - **Bring your own tool**: <https://acrylblends.github.io/docs/guides/bring-your-own-tool> wraps an outside library as a provider of a port.
276
-
277
- ---
278
-
279
- ## If something goes wrong
280
-
281
- | Symptom | Do |
282
- | --- | --- |
283
- | The preflight prints `FIX` lines | run each one, then `npx acrylblends@latest preflight` again |
284
- | `npm create` fails or hangs | check the network; the facilitator has prepared apps |
285
- | `npm install` fails building node-pty | install the C++ toolchain (block 1's **Stuck?**) and run it again |
286
- | A port is taken | use the address the app printed |
287
- | The frame says `Reconnecting...` | wait ten seconds; then `npx acrylblends open` and open the address it prints |
288
- | Settings > Models shows no provider | the host is not running: `Ctrl-C`, `npm run dev` |
289
- | The chat asks for a model | finish block 3, then reload the page |
290
- | The model plans and stops | reply "do it now, without asking for approval" |
291
- | An agent cannot log in | `codex login` / `claude` / pi with `DEEPSEEK_API_KEY`, then open the tab again |
292
- | The app's page is unchanged after an edit | the host did not restart: `Ctrl-C`, `npm run dev` |
293
- | `&&` is an error in PowerShell | Windows PowerShell 5.1: type the two commands as two lines, or join them with `;` |
294
- | Anything else | the **Stuck?** line of the step, then your facilitator |