@acryldev/create-blends 0.0.0-stage → 1.7.0
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 +104 -2
- package/bin/create-acrylblends.js +12 -0
- package/dist/index.d.ts +94 -0
- package/dist/index.js +1069 -0
- package/dist/index.js.map +1 -0
- package/docs/framework/LICENSE +23 -0
- package/docs/framework/README.md +70 -0
- package/docs/framework/agents/index.md +59 -0
- package/docs/framework/api/acryl.md +247 -0
- package/docs/framework/api/context.md +478 -0
- package/docs/framework/api/exception.md +80 -0
- package/docs/framework/api/index.md +12 -0
- package/docs/framework/api/presets.md +62 -0
- package/docs/framework/api/request.md +396 -0
- package/docs/framework/api/routing.md +303 -0
- package/docs/framework/api/summary.md +143 -0
- package/docs/framework/concepts/benchmarks.md +26 -0
- package/docs/framework/concepts/developer-experience.md +5 -0
- package/docs/framework/concepts/middleware.md +21 -0
- package/docs/framework/concepts/motivation.md +14 -0
- package/docs/framework/concepts/routers.md +63 -0
- package/docs/framework/concepts/stacks.md +235 -0
- package/docs/framework/concepts/web-standard.md +27 -0
- package/docs/framework/cordis/acryl-in-a-cordis-app.md +160 -0
- package/docs/framework/cordis/concepts.md +105 -0
- package/docs/framework/cordis/middleware.md +8 -0
- package/docs/framework/cordis/migration-from-0-3.md +111 -0
- package/docs/framework/cordis/migration-from-0-4.md +14 -0
- package/docs/framework/cordis/migration-from-dsh-webserver.md +109 -0
- package/docs/framework/cordis/migration-to-1-0.md +46 -0
- package/docs/framework/cordis/mounting.md +85 -0
- package/docs/framework/cordis/node-server.md +100 -0
- package/docs/framework/cordis/plugin-lifecycle.md +111 -0
- package/docs/framework/cordis/surfaces.md +71 -0
- package/docs/framework/cordis/transport-and-cancellation.md +57 -0
- package/docs/framework/cordis/validation.md +135 -0
- package/docs/framework/getting-started/basic.md +201 -0
- package/docs/framework/getting-started/bun.md +219 -0
- package/docs/framework/getting-started/deploy.md +133 -0
- package/docs/framework/getting-started/desktop.md +80 -0
- package/docs/framework/getting-started/nodejs.md +365 -0
- package/docs/framework/getting-started/other-runtimes.md +30 -0
- package/docs/framework/guides/best-practices.md +231 -0
- package/docs/framework/guides/bring-your-own-tool.md +218 -0
- package/docs/framework/guides/client-modules.md +210 -0
- package/docs/framework/guides/create-acrylblends.md +143 -0
- package/docs/framework/guides/data.md +314 -0
- package/docs/framework/guides/examples.md +3 -0
- package/docs/framework/guides/faq.md +19 -0
- package/docs/framework/guides/forms-and-sessions.md +235 -0
- package/docs/framework/guides/helpers.md +33 -0
- package/docs/framework/guides/jsx-dom.md +301 -0
- package/docs/framework/guides/jsx.md +487 -0
- package/docs/framework/guides/middleware.md +253 -0
- package/docs/framework/guides/production.md +80 -0
- package/docs/framework/guides/rpc.md +878 -0
- package/docs/framework/guides/testing.md +133 -0
- package/docs/framework/guides/validation.md +470 -0
- package/docs/framework/helpers/accepts.md +60 -0
- package/docs/framework/helpers/adapter.md +57 -0
- package/docs/framework/helpers/conninfo.md +77 -0
- package/docs/framework/helpers/cookie.md +232 -0
- package/docs/framework/helpers/css.md +282 -0
- package/docs/framework/helpers/dev.md +64 -0
- package/docs/framework/helpers/factory.md +180 -0
- package/docs/framework/helpers/html.md +123 -0
- package/docs/framework/helpers/jwt.md +184 -0
- package/docs/framework/helpers/proxy.md +115 -0
- package/docs/framework/helpers/route.md +143 -0
- package/docs/framework/helpers/ssg.md +390 -0
- package/docs/framework/helpers/streaming.md +224 -0
- package/docs/framework/helpers/testing.md +118 -0
- package/docs/framework/helpers/websocket.md +208 -0
- package/docs/framework/middleware/builtin/basic-auth.md +165 -0
- package/docs/framework/middleware/builtin/bearer-auth.md +138 -0
- package/docs/framework/middleware/builtin/body-limit.md +71 -0
- package/docs/framework/middleware/builtin/cache.md +99 -0
- package/docs/framework/middleware/builtin/combine.md +94 -0
- package/docs/framework/middleware/builtin/compress.md +59 -0
- package/docs/framework/middleware/builtin/context-storage.md +74 -0
- package/docs/framework/middleware/builtin/cors.md +134 -0
- package/docs/framework/middleware/builtin/csrf.md +105 -0
- package/docs/framework/middleware/builtin/etag.md +54 -0
- package/docs/framework/middleware/builtin/ip-restriction.md +69 -0
- package/docs/framework/middleware/builtin/jsx-renderer.md +283 -0
- package/docs/framework/middleware/builtin/jwk.md +192 -0
- package/docs/framework/middleware/builtin/jwt.md +145 -0
- package/docs/framework/middleware/builtin/language.md +232 -0
- package/docs/framework/middleware/builtin/logger.md +74 -0
- package/docs/framework/middleware/builtin/loopback-only.md +31 -0
- package/docs/framework/middleware/builtin/method-not-allowed.md +48 -0
- package/docs/framework/middleware/builtin/method-override.md +80 -0
- package/docs/framework/middleware/builtin/mount.md +103 -0
- package/docs/framework/middleware/builtin/pretty-json.md +53 -0
- package/docs/framework/middleware/builtin/request-id.md +87 -0
- package/docs/framework/middleware/builtin/secure-headers.md +247 -0
- package/docs/framework/middleware/builtin/timeout.md +98 -0
- package/docs/framework/middleware/builtin/timing.md +100 -0
- package/docs/framework/middleware/builtin/trailing-slash.md +74 -0
- package/docs/framework/middleware/third-party.md +4 -0
- package/docs/framework/workshop/README.md +294 -0
- package/docs/framework/workshop/facilitator.md +101 -0
- package/package.json +54 -3
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
# Bun
|
|
2
|
+
|
|
3
|
+
> **Experimental.** Bun is not a verified runtime yet: the Acryl application code is the same, and the Bun adapter (`acrylblends/bun`) is checked on Bun in the framework's release check (a static file, the client address, a WebSocket echo), but the `bun` template and this guide are not covered by the release checks. Node.js is the verified runtime.
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
[Bun](https://bun.com) is another JavaScript runtime. It's not Node.js. Bun includes a transcompiler, so we can write the code in TypeScript or plain JavaScript.
|
|
7
|
+
Acryl also works on Bun.
|
|
8
|
+
|
|
9
|
+
## 1. Install Bun
|
|
10
|
+
|
|
11
|
+
To install `bun` command, follow the instruction in [the official web site](https://bun.com).
|
|
12
|
+
|
|
13
|
+
## 2. Setup
|
|
14
|
+
|
|
15
|
+
### 2.1. Setup a new project
|
|
16
|
+
|
|
17
|
+
A starter for Bun is available. Start your project with "bun create" command.
|
|
18
|
+
Select `bun` template for this example.
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
bun create acrylblends@latest my-app
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Move into my-app and install the dependencies.
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
cd my-app
|
|
28
|
+
bun install
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### 2.2. Setup an existing project
|
|
32
|
+
|
|
33
|
+
On an existing Bun project, we only need to install `acrylblends` dependencies on the project root directory via
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
bun add acrylblends
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Then add the `dev` command to your existing `package.json`.
|
|
40
|
+
|
|
41
|
+
```json
|
|
42
|
+
{
|
|
43
|
+
"scripts": {
|
|
44
|
+
"dev": "bun run --hot src/index.ts"
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
See the Bun starter template for a minimal example setup. This is the output of running `bun create acrylblends@latest`.
|
|
50
|
+
|
|
51
|
+
## 3. Hello World
|
|
52
|
+
|
|
53
|
+
"Hello World" script is below. Almost the same as writing on other platforms.
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
import { Acryl } from '@acryldev/blends'
|
|
57
|
+
|
|
58
|
+
const app = new Acryl()
|
|
59
|
+
app.get('/', (c) => c.text('Hello Bun!'))
|
|
60
|
+
|
|
61
|
+
export default app
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
If you are setting up Acryl on an existing project, the `bun run dev` command expects the "Hello World" script to be placed in `src/index.ts`
|
|
65
|
+
|
|
66
|
+
## 4. Run
|
|
67
|
+
|
|
68
|
+
Run the command.
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
bun run dev
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Then, access `http://localhost:3000` in your browser.
|
|
75
|
+
|
|
76
|
+
## Change port number
|
|
77
|
+
|
|
78
|
+
You can specify the port number with exporting the `port`.
|
|
79
|
+
|
|
80
|
+
<!-- prettier-ignore -->
|
|
81
|
+
```ts
|
|
82
|
+
import { Acryl } from '@acryldev/blends'
|
|
83
|
+
|
|
84
|
+
const app = new Acryl()
|
|
85
|
+
app.get('/', (c) => c.text('Hello Bun!'))
|
|
86
|
+
|
|
87
|
+
export default {
|
|
88
|
+
port: 3000,
|
|
89
|
+
fetch: app.fetch,
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Serve static files
|
|
94
|
+
|
|
95
|
+
To serve static files, use `serveStatic` from `acrylblends/bun`.
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
import { serveStatic } from '@acryldev/blends/bun'
|
|
99
|
+
|
|
100
|
+
const app = new Acryl()
|
|
101
|
+
|
|
102
|
+
app.use('/static/*', serveStatic({ root: './' }))
|
|
103
|
+
app.use('/favicon.ico', serveStatic({ path: './favicon.ico' }))
|
|
104
|
+
app.get('/', (c) => c.text('You can access: /static/hello.txt'))
|
|
105
|
+
app.get('*', serveStatic({ path: './static/fallback.txt' }))
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
For the above code, it will work well with the following directory structure.
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
./
|
|
112
|
+
├── favicon.ico
|
|
113
|
+
├── src
|
|
114
|
+
└── static
|
|
115
|
+
├── demo
|
|
116
|
+
│ └── index.html
|
|
117
|
+
├── fallback.txt
|
|
118
|
+
├── hello.txt
|
|
119
|
+
└── images
|
|
120
|
+
└── dinotocat.png
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### `rewriteRequestPath`
|
|
124
|
+
|
|
125
|
+
If you want to map `http://localhost:3000/static/*` to `./statics`, you can use the `rewriteRequestPath` option:
|
|
126
|
+
|
|
127
|
+
```ts
|
|
128
|
+
app.get(
|
|
129
|
+
'/static/*',
|
|
130
|
+
serveStatic({
|
|
131
|
+
root: './',
|
|
132
|
+
rewriteRequestPath: (path) =>
|
|
133
|
+
path.replace(/^\/static/, '/statics'),
|
|
134
|
+
})
|
|
135
|
+
)
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### `mimes`
|
|
139
|
+
|
|
140
|
+
You can add MIME types with `mimes`:
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
app.get(
|
|
144
|
+
'/static/*',
|
|
145
|
+
serveStatic({
|
|
146
|
+
mimes: {
|
|
147
|
+
m3u8: 'application/vnd.apple.mpegurl',
|
|
148
|
+
ts: 'video/mp2t',
|
|
149
|
+
},
|
|
150
|
+
})
|
|
151
|
+
)
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### `onFound`
|
|
155
|
+
|
|
156
|
+
You can specify handling when the requested file is found with `onFound`:
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
app.get(
|
|
160
|
+
'/static/*',
|
|
161
|
+
serveStatic({
|
|
162
|
+
// ...
|
|
163
|
+
onFound: (_path, c) => {
|
|
164
|
+
c.header('Cache-Control', `public, immutable, max-age=31536000`)
|
|
165
|
+
},
|
|
166
|
+
})
|
|
167
|
+
)
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### `onNotFound`
|
|
171
|
+
|
|
172
|
+
You can specify handling when the requested file is not found with `onNotFound`:
|
|
173
|
+
|
|
174
|
+
```ts
|
|
175
|
+
app.get(
|
|
176
|
+
'/static/*',
|
|
177
|
+
serveStatic({
|
|
178
|
+
onNotFound: (path, c) => {
|
|
179
|
+
console.log(`${path} is not found, you access ${c.req.path}`)
|
|
180
|
+
},
|
|
181
|
+
})
|
|
182
|
+
)
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### `precompressed`
|
|
186
|
+
|
|
187
|
+
The `precompressed` option checks if files with extensions like `.br` or `.gz` are available and serves them based on the `Accept-Encoding` header. It prioritizes Brotli, then Zstd, and Gzip. If none are available, it serves the original file.
|
|
188
|
+
|
|
189
|
+
```ts
|
|
190
|
+
app.get(
|
|
191
|
+
'/static/*',
|
|
192
|
+
serveStatic({
|
|
193
|
+
precompressed: true,
|
|
194
|
+
})
|
|
195
|
+
)
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Testing
|
|
199
|
+
|
|
200
|
+
You can use `bun:test` for testing on Bun.
|
|
201
|
+
|
|
202
|
+
```ts
|
|
203
|
+
import { describe, expect, it } from 'bun:test'
|
|
204
|
+
import app from '.'
|
|
205
|
+
|
|
206
|
+
describe('My first test', () => {
|
|
207
|
+
it('Should return 200 Response', async () => {
|
|
208
|
+
const req = new Request('http://localhost/')
|
|
209
|
+
const res = await app.fetch(req)
|
|
210
|
+
expect(res.status).toBe(200)
|
|
211
|
+
})
|
|
212
|
+
})
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Then, run the command.
|
|
216
|
+
|
|
217
|
+
```sh
|
|
218
|
+
bun test index.test.ts
|
|
219
|
+
```
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# Deploy
|
|
2
|
+
|
|
3
|
+
This page runs an app made by `npm create @acryldev/blends@latest` (the `nodejs` and `notes` templates) on a Linux server with Node.js 22.19 or later: install, start, keep it running, put HTTPS in front, and look after the SQLite file.
|
|
4
|
+
The snippets are examples to adapt: check them against your own server before relying on them.
|
|
5
|
+
|
|
6
|
+
## What the template already does
|
|
7
|
+
|
|
8
|
+
- **Port and address.** `src/index.ts` reads `PORT` (default 3000) and `HOST` (default `127.0.0.1`). The default is local on purpose, and `serve()` without a `hostname` binds `127.0.0.1` too (from acrylblends 0.7.2; earlier versions listened on every interface). In a container, set `HOST=0.0.0.0`.
|
|
9
|
+
- **Graceful stop.** On `SIGTERM` and `SIGINT` the server stops taking requests, closes idle connections, lets the requests in flight finish, closes the database (the `notes` template) and exits with 0. A connection that never ends cannot keep it alive past 10 seconds (it then exits with 1).
|
|
10
|
+
- **Errors.** An error answers `500 Internal Server Error` with no stack and no detail; the stack goes to the log (standard error).
|
|
11
|
+
- **Cookies.** The `notes` template marks its session cookie `Secure` when the request is HTTPS, or when `TRUST_PROXY=1` and the proxy sends `X-Forwarded-Proto: https`.
|
|
12
|
+
|
|
13
|
+
## Environment variables
|
|
14
|
+
|
|
15
|
+
| Variable | Default | Meaning |
|
|
16
|
+
| --- | --- | --- |
|
|
17
|
+
| `NODE_ENV` | unset | set it to `production` on the server |
|
|
18
|
+
| `PORT` | `3000` | the port to listen on |
|
|
19
|
+
| `HOST` | `127.0.0.1` | the address to bind. `0.0.0.0` exposes the app to the network: do it in a container or when nothing else is in front |
|
|
20
|
+
| `NOTES_DB` | `data/notes.sqlite` in the working directory | the SQLite file (`notes` template); `CHAT_DB` is the `chat` template's (`data/chat.sqlite`). The folder is created, and the migrations in `migrations/` run at start. See [Data](../guides/data.md) |
|
|
21
|
+
| `TRUST_PROXY` | unset | `1` when a reverse proxy you run terminates HTTPS in front of the app (`notes` template) |
|
|
22
|
+
| `PUBLIC_ORIGIN` | unset | the address in the browser, for example `https://notes.example.com`. Behind a proxy the app sees `http://127.0.0.1:3000`, so csrf needs to be told which origin is the site (`notes` template) |
|
|
23
|
+
|
|
24
|
+
Keep secrets out of the repository: put them in an environment file the service reads (below), readable only by the service user.
|
|
25
|
+
|
|
26
|
+
## Install and start
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
git clone <your repository> /srv/notes && cd /srv/notes
|
|
30
|
+
npm ci --omit=dev
|
|
31
|
+
NODE_ENV=production PORT=3000 npm start
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`npm ci --omit=dev` installs `acrylblends` and `typescript`. `typescript` is a normal dependency on purpose (it is why a production install is bigger than the framework alone, about 20 MB more): `.tsx` pages are compiled when the app starts, by `acrylblends/node-server/register`, with the app's own `typescript`.
|
|
35
|
+
There is no build step today. When a build step appears (compiling client code, for instance) it belongs in `npm run build` before `npm start`, not in the start command.
|
|
36
|
+
|
|
37
|
+
## Keep it running with systemd
|
|
38
|
+
|
|
39
|
+
`/etc/systemd/system/notes.service`:
|
|
40
|
+
|
|
41
|
+
```ini
|
|
42
|
+
[Unit]
|
|
43
|
+
Description=Notes
|
|
44
|
+
After=network.target
|
|
45
|
+
|
|
46
|
+
[Service]
|
|
47
|
+
User=notes
|
|
48
|
+
WorkingDirectory=/srv/notes
|
|
49
|
+
EnvironmentFile=/etc/notes.env
|
|
50
|
+
ExecStart=/usr/bin/node --import acrylblends/node-server/register src/index.ts
|
|
51
|
+
Restart=on-failure
|
|
52
|
+
TimeoutStopSec=15
|
|
53
|
+
NoNewPrivileges=true
|
|
54
|
+
ProtectSystem=strict
|
|
55
|
+
ReadWritePaths=/var/lib/notes
|
|
56
|
+
|
|
57
|
+
[Install]
|
|
58
|
+
WantedBy=multi-user.target
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`/etc/notes.env` (mode `0640`, owned by root, group `notes`):
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
NODE_ENV=production
|
|
65
|
+
PORT=3000
|
|
66
|
+
HOST=127.0.0.1
|
|
67
|
+
NOTES_DB=/var/lib/notes/notes.sqlite
|
|
68
|
+
TRUST_PROXY=1
|
|
69
|
+
PUBLIC_ORIGIN=https://notes.example.com
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
sudo useradd --system --home /srv/notes notes
|
|
74
|
+
sudo install -d -o notes -g notes /var/lib/notes
|
|
75
|
+
sudo systemctl daemon-reload && sudo systemctl enable --now notes
|
|
76
|
+
sudo systemctl stop notes # sends SIGTERM; the app exits within seconds
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`ExecStart` runs `node` directly (not `npm start`) so the signal reaches the app and not an `npm` wrapper.
|
|
80
|
+
|
|
81
|
+
## Behind a reverse proxy
|
|
82
|
+
|
|
83
|
+
Let the proxy handle HTTPS and keep the app on `127.0.0.1`.
|
|
84
|
+
|
|
85
|
+
Caddy (`Caddyfile`), which also obtains the certificate:
|
|
86
|
+
|
|
87
|
+
```text
|
|
88
|
+
notes.example.com {
|
|
89
|
+
reverse_proxy 127.0.0.1:3000
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
nginx (certificates from your own tool, for example certbot):
|
|
94
|
+
|
|
95
|
+
```nginx
|
|
96
|
+
server {
|
|
97
|
+
listen 443 ssl;
|
|
98
|
+
server_name notes.example.com;
|
|
99
|
+
# ssl_certificate and ssl_certificate_key here
|
|
100
|
+
|
|
101
|
+
location / {
|
|
102
|
+
proxy_pass http://127.0.0.1:3000;
|
|
103
|
+
proxy_set_header Host $host;
|
|
104
|
+
proxy_set_header X-Forwarded-Proto $scheme;
|
|
105
|
+
proxy_set_header X-Forwarded-For $remote_addr;
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Both pass `X-Forwarded-Proto`. Set `TRUST_PROXY=1` only when the app is reachable **only** through that proxy (it listens on `127.0.0.1`): the header is otherwise something any client can send.
|
|
111
|
+
|
|
112
|
+
## The SQLite file and backups
|
|
113
|
+
|
|
114
|
+
The database is one file (plus `-wal` and `-shm` files while it is open). Keep it outside the code folder (`NOTES_DB=/var/lib/notes/notes.sqlite`), owned by the service user, on a disk you back up.
|
|
115
|
+
Do not copy the file while the app writes to it. Take a consistent copy with SQLite's backup, which is safe on a running database:
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
import { DatabaseSync, backup } from 'node:sqlite'
|
|
119
|
+
|
|
120
|
+
const db = new DatabaseSync(process.env.NOTES_DB ?? 'data/notes.sqlite')
|
|
121
|
+
await backup(db, `/var/backups/notes-${new Date().toISOString().slice(0, 10)}.db`)
|
|
122
|
+
db.close()
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
or, with the `sqlite3` command line tool installed: `sqlite3 /var/lib/notes/notes.sqlite ".backup '/var/backups/notes.db'"`. Run it from cron or a systemd timer and copy the result off the machine. To restore, stop the service and put the backup file in place of `notes.sqlite`.
|
|
126
|
+
|
|
127
|
+
## Check it
|
|
128
|
+
|
|
129
|
+
```sh
|
|
130
|
+
curl -I http://127.0.0.1:3000/ # the app, directly
|
|
131
|
+
curl -I https://notes.example.com/ # through the proxy
|
|
132
|
+
journalctl -u notes -n 50 # the log, including error stacks
|
|
133
|
+
```
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Desktop
|
|
2
|
+
|
|
3
|
+
An Acryl app also runs as a desktop app: an Electron window opens on the app's own server. It is the same app and the same code as `npm run dev`; nothing in the app changes. A Blend app that runs inside the ACRYL frame
|
|
4
|
+
(it has `scripts/ide-host.mjs`) gets the whole frame in the window, the same one `npm run dev` serves to the browser: see [The frame in the window](#the-frame-in-the-window). This page covers a plain Acryl app (the `nodejs`
|
|
5
|
+
template) and a Blend app (the `agent` template or any other `acrylblends init` template). It runs from source today: packaging a distributable app (dmg, exe, deb) is not part of it yet.
|
|
6
|
+
|
|
7
|
+
## Add it
|
|
8
|
+
|
|
9
|
+
In an app made by `npm create @acryldev/blends@latest my-app nodejs` (or `notes`, `chat`):
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
cd my-app
|
|
13
|
+
npm install
|
|
14
|
+
npx acrylblends add desktop
|
|
15
|
+
npm install
|
|
16
|
+
npm run desktop
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
In a Blend app, the same two commands (`npx acrylblends add desktop-shell`, `npm install`) add the Blend form of the shell, and `npx acrylblends init my-app --template todo --desktop` creates a Blend app with it already in.
|
|
20
|
+
`acrylblends add desktop-shell` chooses the right form: a Blend app (it depends on `@acryldev/instance`) or a plain Acryl app.
|
|
21
|
+
|
|
22
|
+
## What it adds
|
|
23
|
+
|
|
24
|
+
- `plugins/desktop-web/` (a plain app) or the `@acryldev/desktop-shell` package (a Blend app, a dependency at the exact version of this release): the window code. Only it imports `electron`; the app's own code never does.
|
|
25
|
+
- `electron` as a development dependency (pinned to 44.9.3) and the script `npm run desktop`.
|
|
26
|
+
- `.acrylblends/` in `.gitignore`: Electron's user data (window state, cache, logs) lives in `.acrylblends/electron` inside the app's own folder, never in the user's application-data folder.
|
|
27
|
+
|
|
28
|
+
## What `npm run desktop` does
|
|
29
|
+
|
|
30
|
+
1. For a frame app, attaches to the running frame or starts its host (see [The frame in the window](#the-frame-in-the-window)). Otherwise it serves the app on `127.0.0.1` with a free port: for a plain app, `app.fetch` from `src/app.ts` (`export default app`) through `acrylblends/node-server`; for a Blend app, its own `createApp`.
|
|
31
|
+
2. Takes a single-instance lock: a second launch of the same app focuses the first window and exits.
|
|
32
|
+
3. Opens one window on the server's address, with a locked-down renderer (context isolation, no Node in the page, the sandbox, web security). Navigation stays on the app's own origin; a link to any other `http(s)` or `mailto` address opens in the system browser.
|
|
33
|
+
4. When the window closes (or on SIGINT or SIGTERM), stops the server or frame host it started (never one it attached to) and exits.
|
|
34
|
+
|
|
35
|
+
## The frame in the window
|
|
36
|
+
|
|
37
|
+
A Blend app made with the frame (`npm run dev` runs `scripts/ide-host.mjs`) opens the ACRYL frame in its desktop window, not only its page: the left panel with the
|
|
38
|
+
projects and sessions, the right panel with Files, Changes and Review, Settings, terminal tabs, the DSH chat, and the app's own page in a browser tile. It is the
|
|
39
|
+
same frame the browser shows; the desktop builds nothing of its own.
|
|
40
|
+
|
|
41
|
+
1. When the frame already runs for this folder (`npm run dev` in another terminal), the window attaches to it: it reads the address the host keeps in
|
|
42
|
+
`.acrylblends/frame-url.json` (owner-only, with the launch token) and opens it. Closing the window leaves that host running.
|
|
43
|
+
2. Otherwise the window starts the host itself, exactly as `npm run dev` does (the same npm and Node that ran `npm run desktop`; the host never runs inside
|
|
44
|
+
Electron), and opens the address it prints. Closing the window stops that host and everything it started, including its terminals, so its port is free
|
|
45
|
+
again. Ctrl-C in the terminal does the same: Electron runs in a process group of its own, and `npm run desktop` passes it exactly one signal (a second
|
|
46
|
+
one would end Electron before it could stop the host).
|
|
47
|
+
3. Navigation follows ACRYL Desktop's rule: the frame's own address stays in the window, and its tiles (the app's page in an iframe) load freely. A link to any
|
|
48
|
+
other `http(s)` or `mailto` address opens in the system browser, and nothing else opens at all.
|
|
49
|
+
4. The door's `window list` shows each window's address without the launch token.
|
|
50
|
+
|
|
51
|
+
The application menu's `Settings...` (`Cmd+,` on macOS, in the app menu; `Ctrl+,` and the File menu on Windows and Linux) opens the frame's own Settings, the dialog the left panel's Settings button opens. `acrylblends.desktopPath` does not apply to a frame app, because the frame opens the app's page in its tile on first run.
|
|
52
|
+
|
|
53
|
+
## The first launch downloads Electron
|
|
54
|
+
|
|
55
|
+
`npm install` does not download Electron's binary (Electron 44 has no install script). The first `npm run desktop` does: about 100 MB, once per machine, then it is cached. Behind a proxy or mirror set `ELECTRON_MIRROR`
|
|
56
|
+
(and `ELECTRON_CACHE` to reuse a download); if the download is blocked, run `npx install-electron` where the mirror is reachable.
|
|
57
|
+
|
|
58
|
+
## Linux: Ubuntu 23.10 and later
|
|
59
|
+
|
|
60
|
+
Ubuntu 23.10 and later restrict unprivileged user namespaces (`kernel.apparmor_restrict_unprivileged_userns=1`). Chromium's sandbox needs them, and an Electron unpacked by npm into `node_modules` has no AppArmor profile, so Electron stops at the start with "The SUID sandbox helper binary was found, but is not configured correctly" before the app runs.
|
|
61
|
+
|
|
62
|
+
`npm run desktop` starts through the shell's launcher (`acryl-desktop` in a Blend app, `plugins/desktop-web/launch.ts` in a plain one), which reads that sysctl. **Only when it is `1` on Linux** it starts Electron with `--no-sandbox` and prints one line saying so; on macOS, on Windows and on any Linux without the restriction Electron starts with its sandbox, as it always does. The window's renderer is still locked down (context isolation, no Node in the page, web security); what is lost is Chromium's process sandbox around it.
|
|
63
|
+
|
|
64
|
+
To keep the sandbox, give Electron an AppArmor profile that allows `userns`, as the VS Code and Chrome `.deb` packages do. Save this as `/etc/apparmor.d/my-app-electron` (the path is the one in your app's `node_modules`), then `sudo apparmor_parser -r /etc/apparmor.d/my-app-electron`:
|
|
65
|
+
|
|
66
|
+
```text
|
|
67
|
+
abi <abi/4.0>,
|
|
68
|
+
include <tunables/global>
|
|
69
|
+
|
|
70
|
+
profile my-app-electron /path/to/my-app/node_modules/electron/dist/electron flags=(unconfined) {
|
|
71
|
+
userns,
|
|
72
|
+
include if exists <local/my-app-electron>
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The launcher then still sees the sysctl as `1` and passes `--no-sandbox`; set `ACRYLBLENDS_DESKTOP_SANDBOX=1` to start with the sandbox anyway.
|
|
77
|
+
|
|
78
|
+
## A different start page
|
|
79
|
+
|
|
80
|
+
The window opens on `/`. To open another path, set it in `package.json`: `"acrylblends": { "desktopPath": "/todo" }`.
|