kreftjs 0.0.3-beta → 0.0.4-beta

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 (53) hide show
  1. package/README.md +12 -12
  2. package/bin/add.js +11 -11
  3. package/bin/artisan-more.js +41 -41
  4. package/bin/artisan.js +41 -41
  5. package/bin/backend/command.js +1 -1
  6. package/bin/backend/factory.js +1 -1
  7. package/bin/backend/index.js +3 -3
  8. package/bin/backend/model.js +2 -2
  9. package/bin/backend/notifications.js +1 -1
  10. package/bin/backend/queue.js +2 -2
  11. package/bin/backend/schedule.js +2 -2
  12. package/bin/backend/seo-pages.js +1 -1
  13. package/bin/backend/storage.js +1 -1
  14. package/bin/backend/support.js +4 -4
  15. package/bin/backend/typescript.js +1 -1
  16. package/bin/build.js +11 -11
  17. package/bin/db-api.js +3 -3
  18. package/bin/db.js +1 -1
  19. package/bin/deps.js +6 -6
  20. package/bin/electron.js +11 -11
  21. package/bin/env.js +2 -2
  22. package/bin/guard.js +2 -2
  23. package/bin/kreftjs-config.js +1 -1
  24. package/bin/kreftjs.js +105 -105
  25. package/bin/layout.js +1 -1
  26. package/bin/no-auth.js +4 -4
  27. package/bin/prerender.js +4 -4
  28. package/bin/server-routes.js +2 -2
  29. package/bin/ssr.js +2 -2
  30. package/bin/terminal.js +1 -1
  31. package/bin/to-ts.js +1 -1
  32. package/bin/update.js +14 -14
  33. package/bin/urls-file.js +1 -1
  34. package/bin/vite.js +11 -11
  35. package/docs/Docs.kreftjs +1 -1
  36. package/docs/README.md +140 -123
  37. package/kreftjs.d.ts +1 -1
  38. package/kreftjs.js +18 -18
  39. package/package.json +1 -1
  40. package/templates/app/README.md +20 -20
  41. package/templates/app/backend/database/migrations/0001_01_01_000000_create_users_table.js +1 -1
  42. package/templates/app/backend/database/migrations/0001_01_01_000002_create_jobs_table.js +1 -1
  43. package/templates/app/backend/database/seeders/DatabaseSeeder.js +1 -1
  44. package/templates/app/backend/routes/api.js +1 -1
  45. package/templates/app/backend/routes/console.js +2 -2
  46. package/templates/app/frontend/errors/ErrorMonitor.kreftjs +2 -2
  47. package/templates/app/frontend/index.html +1 -1
  48. package/templates/app/frontend/kreftjs.d.ts +1 -1
  49. package/templates/app/frontend/kreftjs.js +18 -18
  50. package/templates/app/frontend/pages/Dashboard.kreftjs +1 -1
  51. package/templates/app/frontend/pages/ErrorMonitor.kreftjs +1 -1
  52. package/templates/app/frontend/pages/Home.kreftjs +2 -2
  53. package/templates/errors/ErrorMonitor.kreftjs +1 -1
package/docs/README.md CHANGED
@@ -22,7 +22,7 @@ action add() { count++ }
22
22
  | **The `.kreftjs` language** | `state`, `derive`, `action`, `watch`, props, events, slots, stores, a router with layouts and nested routes, forms with validation, animations. |
23
23
  | **The backend** | `Route`, controllers, an Active Record `Model`, migrations, seeders, factories, jobs, mail, cache, file storage, policies, scheduling. |
24
24
  | **Authentication** | Sign-in pages, password reset, email verification, two-factor codes, device sessions and API tokens, ready in every new project (leave them out with `--no-auth`). |
25
- | **Tooling** | `kreftjs dev` with hot reload that keeps state, DevTools, an error monitor, `kreftjs build`, TypeScript, Vite and Electron support. |
25
+ | **Tooling** | `kreft dev` with hot reload that keeps state, DevTools, an error monitor, `kreft build`, TypeScript, Vite and Electron support. |
26
26
  | **Security by default** | Escaped views, CSRF protection, hashed passwords, rate limits, hardened package installs. See [Security overview](#security-overview). |
27
27
 
28
28
  ### How the docs are organised
@@ -34,7 +34,7 @@ action add() { count++ }
34
34
  5. **Security** and **Reference** are for checking details.
35
35
 
36
36
  > [!NOTE]
37
- > Some chapters mention a few tools by name only (for example `kreftjs make:model`). Run `kreftjs list` to see every command that your installed version has.
37
+ > Some chapters mention a few tools by name only (for example `kreft make:model`). Run `kreft list` to see every command that your installed version has.
38
38
 
39
39
  ## Installation
40
40
 
@@ -42,7 +42,7 @@ action add() { count++ }
42
42
 
43
43
  | You need | Why |
44
44
  |---|---|
45
- | [Node.js](https://nodejs.org) **22.5 or newer** (npm comes with it) | Runs the `kreftjs` command, the dev server and the backend. 22.5 also gives you SQLite with nothing to install. |
45
+ | [Node.js](https://nodejs.org) **22.5 or newer** (npm comes with it) | Runs the `kreft` command, the dev server and the backend. 22.5 also gives you SQLite with nothing to install. |
46
46
  | A terminal | macOS Terminal, Windows PowerShell, or any Linux shell. |
47
47
  | A modern browser | Chrome, Edge, Firefox or Safari. |
48
48
  | MySQL, PostgreSQL or Redis | Only if you choose them. SQLite needs nothing. |
@@ -57,7 +57,7 @@ node --version # v22.5.0 or higher
57
57
 
58
58
  Pick one way.
59
59
 
60
- **1. Once, for every project (recommended).** The `kreftjs` command then works in any folder:
60
+ **1. Once, for every project (recommended).** The `kreft` command then works in any folder (the package is called `kreftjs`):
61
61
 
62
62
  ```bash
63
63
  npm i -g kreftjs
@@ -82,17 +82,17 @@ npx kreftjs dev
82
82
  ### Check that it works
83
83
 
84
84
  ```bash
85
- kreftjs --version # for example 0.0.3-beta
86
- kreftjs about # Kreft and Node.js versions, this project's settings and drivers
87
- kreftjs list # every command your version has
85
+ kreft --version # for example 0.0.4-beta
86
+ kreft about # Kreft and Node.js versions, this project's settings and drivers
87
+ kreft list # every command your version has
88
88
  ```
89
89
 
90
- `kreft` is a shorter name for the same command.
90
+ `kreftjs` is a longer name for the same command; both work.
91
91
 
92
92
  ### Set up your editor
93
93
 
94
94
  ```bash
95
- kreftjs vscode
95
+ kreft vscode
96
96
  ```
97
97
 
98
98
  installs colors and snippets for `.kreftjs` files in VS Code (also Cursor and VSCodium). Restart the editor afterwards.
@@ -102,11 +102,11 @@ installs colors and snippets for `.kreftjs` files in VS Code (also Cursor and VS
102
102
  ```bash
103
103
  npm i -g kreftjs@latest # the command (or: npm i -D kreftjs@latest inside a project)
104
104
  cd my-app
105
- kreftjs update --check # what would change
106
- kreftjs update --core # refresh this app's kreftjs.js and type files (a backup is saved)
105
+ kreft update --check # what would change
106
+ kreft update --core # refresh this app's kreftjs.js and type files (a backup is saved)
107
107
  ```
108
108
 
109
- Every app has its own copy of the browser runtime, `frontend/kreftjs.js`. Updating the command does not touch it, so an existing app keeps its old version until you run `kreftjs update --core` inside it.
109
+ Every app has its own copy of the browser runtime, `frontend/kreftjs.js`. Updating the command does not touch it, so an existing app keeps its old version until you run `kreft update --core` inside it.
110
110
 
111
111
  ### Uninstall
112
112
 
@@ -116,7 +116,7 @@ npm rm -g kreftjs
116
116
 
117
117
  ### Working on Kreft itself
118
118
 
119
- Run `npm link` inside the Kreft folder. The `kreftjs` command then runs that folder's code, and every edit shows at once. Undo it with `npm unlink -g kreftjs`.
119
+ Run `npm link` inside the Kreft folder. The `kreft` command then runs that folder's code, and every edit shows at once. Undo it with `npm unlink -g kreftjs`.
120
120
 
121
121
  ### If something goes wrong
122
122
 
@@ -125,9 +125,9 @@ Run `npm link` inside the Kreft folder. The `kreftjs` command then runs that fol
125
125
  | `command not found: kreftjs` | npm's global folder is not on your `PATH`. Run `npm config get prefix`, add its `bin` folder to `PATH`, and open a new terminal. |
126
126
  | `EACCES: permission denied` while installing | Do not use `sudo`. Install Node with [nvm](https://github.com/nvm-sh/nvm), or run `npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to `PATH`. |
127
127
  | `SQLite needs Node.js 22.5 or newer` | Update Node.js. `node --version` must show 22.5.0 or higher. |
128
- | `kreftjs --version` shows an old number | Another copy comes first on your `PATH`. Run `which -a kreftjs` (Windows: `where kreftjs`) and remove the old one. |
128
+ | `kreft --version` shows an old number | Another copy comes first on your `PATH`. Run `which -a kreftjs` (Windows: `where kreftjs`) and remove the old one. |
129
129
  | PowerShell says "running scripts is disabled" (Windows) | Run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`, or use Command Prompt. |
130
- | The browser shows a blank page or "Not found: /" | Run `kreftjs dev` from the project's top folder (the one with `frontend/` and `backend/`). The dev server serves `frontend/`. |
130
+ | The browser shows a blank page or "Not found: /" | Run `kreft dev` from the project's top folder (the one with `frontend/` and `backend/`). The dev server serves `frontend/`. |
131
131
 
132
132
  Next: [Your first app](#your-first-app).
133
133
 
@@ -138,26 +138,43 @@ Kreft is Som.js under a new name (the package and command are `kreftjs`), and an
138
138
  - **Files:** `.som` (and `.kreft`) files still compile, next to `.kreftjs` ones. A name that is missing with one extension is tried with the others. Everything the tools write is `.kreftjs`.
139
139
  - **Templates:** `s-if`, `s-each` and every other `s-` directive are read as `k-if`, `k-each` …, and `<som-view>`, `<som-link>` … as `<kreft-view>`, `<kreft-link>` …
140
140
  - **JavaScript:** `Som` and `Kreft` are other names for `Kreftjs` (same object; `Som` is deprecated), and `Som.compileSom` is `Kreftjs.compile`.
141
- - **Command:** use `kreftjs` (or `kreft`). Kreft does not install a `som` command, so it can be installed next to an old Som.js without an `EEXIST` error; remove the old one with `npm rm -g somjs`.
141
+ - **Command:** use `kreft` (or `kreftjs`). Kreft does not install a `som` command, so it can be installed next to an old Som.js without an `EEXIST` error; remove the old one with `npm rm -g somjs`.
142
142
  - **Server code:** `require('somjs/server')` (also `som/server`, `@somjs/server`, `kreft/server`) still works; new code uses `require('kreftjs/server')`.
143
143
  - **Settings:** `kreft.config.json`, `som.config.json` and `SOM_` environment variables (`SOM_SSR`, `SOM_ALLOWED_HOSTS` …) are read when the `kreftjs.config.json` file or the `KREFT_` variable is missing.
144
144
  - **Cookies:** new projects use `kreft_session`, `kreft_2fa` and `kreft_bypass`. An existing project keeps its `som_` names until you change `app/Auth/Session.js`, and the framework's CSRF check accepts both.
145
145
  - **Kept on purpose:** the `som_migrations` table, the `som:` prefix of saved data in `localStorage`, and the `som:` Redis keys of the queue. Renaming them needs a migration, planned for 3.1.
146
146
 
147
- To move a project over, rename `*.som` (or `*.kreft`) to `*.kreftjs` (and the paths that mention them), run `kreftjs update` and replace `s-` with `k-`.
147
+ To move a project over, rename `*.som` (or `*.kreft`) to `*.kreftjs` (and the paths that mention them), run `kreft update` and replace `s-` with `k-`.
148
148
 
149
149
  ## Your first app
150
150
 
151
151
  Create a project, move into it and start the development server:
152
152
 
153
153
  ```bash
154
- kreftjs new my-app # asks: JavaScript or TypeScript?
154
+ kreft new my-app # asks: JavaScript or TypeScript?
155
155
  cd my-app
156
156
  npm run dev
157
157
  ```
158
158
 
159
159
  Pass `--js` or `--ts` to skip the question, and `--db sqlite` or `--ui tailwind` (also `bootstrap`, `bulma`, `pico`) to start with a database or a CSS library.
160
160
 
161
+ Options can be combined. For example, a Bootstrap app without login pages:
162
+
163
+ ```bash
164
+ kreft new app-name --ui bootstrap --no-auth
165
+ ```
166
+
167
+ More examples:
168
+
169
+ ```bash
170
+ kreft new shop --db mysql --ts # TypeScript, with a MySQL database
171
+ kreft new site --ui tailwind --no-auth # Tailwind, no sign-in
172
+ kreft new desk --electron # with desktop-app support
173
+ ```
174
+
175
+ > [!NOTE]
176
+ > Write the option values exactly: `bootstrap` (not `bootstap`), `tailwind`, `bulma` or `pico`. Any other value stops with a message that lists the allowed ones.
177
+
161
178
  A new app comes with login, registration, password reset, email verification, a profile and an admin area. It asks whether you want them; pass `--auth` or `--no-auth` to skip the question. `--no-auth` starts a plain site: the welcome page, the docs, the error monitor and the tests (and the Todos example with `--db`), with no users table, sessions or sign-in pages.
162
179
 
163
180
  Open the address the terminal shows (normally `http://localhost:8000`). If that port is busy, the next free one is used.
@@ -195,7 +212,7 @@ state name = 'World'
195
212
 
196
213
  ## Project structure
197
214
 
198
- `kreftjs new` creates two folders that never mix: `frontend/` is what browsers receive, `backend/` is the server and is never reachable over HTTP.
215
+ `kreft new` creates two folders that never mix: `frontend/` is what browsers receive, `backend/` is the server and is never reachable over HTTP.
199
216
 
200
217
  ```text
201
218
  my-app/
@@ -223,13 +240,13 @@ my-app/
223
240
 
224
241
  ### Why the two folders matter
225
242
 
226
- - `kreftjs dev` and `kreftjs build` serve only `frontend/`. The `backend/` folder, database files and `.env` have no web address.
227
- - On macOS and Linux `kreftjs new` gives `backend/` and `.env` permissions that only the owner can read.
243
+ - `kreft dev` and `kreft build` serve only `frontend/`. The `backend/` folder, database files and `.env` have no web address.
244
+ - On macOS and Linux `kreft new` gives `backend/` and `.env` permissions that only the owner can read.
228
245
  - Files such as `.env`, `*.db`, `*.pem`, `package.json` and `kreftjs.config.json` are refused even if requested by name.
229
246
 
230
247
  ### Adding a CSS library
231
248
 
232
- Any CSS library works. Add its `<link>` to `index.html`, or install it and import the file from a `.kreftjs` file; it becomes a `<link>` added once, and `kreftjs build` copies it (with its fonts and images) into `dist/vendor/`.
249
+ Any CSS library works. Add its `<link>` to `index.html`, or install it and import the file from a `.kreftjs` file; it becomes a `<link>` added once, and `kreft build` copies it (with its fonts and images) into `dist/vendor/`.
233
250
 
234
251
  ```html
235
252
  import 'bootstrap/dist/css/bootstrap.min.css' // npm i bootstrap
@@ -238,11 +255,11 @@ import './theme.css' // your own file, next to this .
238
255
 
239
256
  ### npm packages in the browser
240
257
 
241
- Install a package with `kreftjs add`, then import it in any `.kreftjs` file:
258
+ Install a package with `kreft add`, then import it in any `.kreftjs` file:
242
259
 
243
260
  ```bash
244
- kreftjs add dayjs nanoid lodash
245
- kreftjs add -D esbuild # once per project: it prepares packages for the browser
261
+ kreft add dayjs nanoid lodash
262
+ kreft add -D esbuild # once per project: it prepares packages for the browser
246
263
  ```
247
264
 
248
265
  ```html
@@ -256,7 +273,7 @@ state id = nanoid()
256
273
  </view>
257
274
  ```
258
275
 
259
- `kreftjs dev` serves each package as one browser-ready file and tells the browser where it is with an import map. Old-style packages (`module.exports`, such as lodash) work too.
276
+ `kreft dev` serves each package as one browser-ready file and tells the browser where it is with an import map. Old-style packages (`module.exports`, such as lodash) work too.
260
277
 
261
278
  # The Kreft language
262
279
 
@@ -867,7 +884,7 @@ A page can also fill other places in its layout:
867
884
 
868
885
  ### Error pages
869
886
 
870
- Each HTTP error can have its own page in `errors/`. Turn them on with `errors: 'errors'` in the router. New projects already have the folder (`kreftjs make:errors` adds it to an older one):
887
+ Each HTTP error can have its own page in `errors/`. Turn them on with `errors: 'errors'` in the router. New projects already have the folder (`kreft make:errors` adds it to an older one):
871
888
 
872
889
  ```text
873
890
  errors/401.kreftjs 402.kreftjs 403.kreftjs 404.kreftjs 419.kreftjs 429.kreftjs 500.kreftjs 503.kreftjs
@@ -945,7 +962,7 @@ load posts = api.get('/api/posts', { query: { q: query || undefined, page } })
945
962
 
946
963
  ### Tables
947
964
 
948
- For tables served by `kreftjs dev --db` or the automatic table API, `table(name)` gives ready-made calls:
965
+ For tables served by `kreft dev --db` or the automatic table API, `table(name)` gives ready-made calls:
949
966
 
950
967
  ```html
951
968
  const posts = table('posts')
@@ -998,14 +1015,14 @@ Requests to your own backend also send `X-XSRF-TOKEN` from the `XSRF-TOKEN` cook
998
1015
  ### A practice API
999
1016
 
1000
1017
  ```bash
1001
- kreftjs dev --api db.json # a REST API at /api, made from a JSON file
1002
- kreftjs dev --api db.json --delay 500 # answer slowly, to see loading states
1018
+ kreft dev --api db.json # a REST API at /api, made from a JSON file
1019
+ kreft dev --api db.json --delay 500 # answer slowly, to see loading states
1003
1020
  ```
1004
1021
 
1005
1022
  It gives GET and POST on `/api/posts`, GET, PUT, PATCH and DELETE on `/api/posts/1`, search with `?q=text`, filters with `?field=value`, and standard paging and sorting.
1006
1023
 
1007
1024
  > [!WARNING]
1008
- > `--api` and `--db` are for development. They have no login. `kreftjs dev` answers only your own computer, and refuses requests that change data when they come from another web site, but do not expose them to the internet. In production, write real routes (see [Routing](#routing)).
1025
+ > `--api` and `--db` are for development. They have no login. `kreft dev` answers only your own computer, and refuses requests that change data when they come from another web site, but do not expose them to the internet. In production, write real routes (see [Routing](#routing)).
1009
1026
 
1010
1027
  ## Forms and validation
1011
1028
 
@@ -1130,7 +1147,7 @@ Blade and similar engines use `{{ }}`; Kreft uses `{ }`, so they do not clash. P
1130
1147
 
1131
1148
  ## Routing
1132
1149
 
1133
- A project made with `kreftjs new` has a Node.js backend. `kreftjs dev` and `kreftjs serve` load `backend/routes/api.js` by themselves, every address in it starts with `/api`, and `kreftjs dev` picks up each change you save. The backend folder never reaches the browser.
1150
+ A project made with `kreft new` has a Node.js backend. `kreft dev` and `kreft serve` load `backend/routes/api.js` by themselves, every address in it starts with `/api`, and `kreft dev` picks up each change you save. The backend folder never reaches the browser.
1134
1151
 
1135
1152
  ```js
1136
1153
  // routes/api.js
@@ -1151,7 +1168,7 @@ Route.prefix('admin').middleware(['auth', 'admin']).group(() => { … })
1151
1168
 
1152
1169
  - Parameters are written `{post}`, or `{post?}` when optional.
1153
1170
  - A route can have a name (`.name('…')`), a pattern (`.whereNumber('id')`) and middleware (`.middleware('auth')`).
1154
- - `kreftjs route:list` prints every route with its name, controller and middleware.
1171
+ - `kreft route:list` prints every route with its name, controller and middleware.
1155
1172
 
1156
1173
  ### Namespaces
1157
1174
 
@@ -1197,7 +1214,7 @@ class PostController {
1197
1214
  module.exports = PostController
1198
1215
  ```
1199
1216
 
1200
- Generate one with `kreftjs make:controller PostController --api` (also `--model Post`, `--route=api`, `--auth`).
1217
+ Generate one with `kreft make:controller PostController --api` (also `--model Post`, `--route=api`, `--auth`).
1201
1218
 
1202
1219
  ### The request
1203
1220
 
@@ -1233,7 +1250,7 @@ return PostResource.collection(await Post.paginate(15)) // { data, meta
1233
1250
  await req.authorize('update', post) // app/Policies/PostPolicy.js
1234
1251
  ```
1235
1252
 
1236
- Generate them with `kreftjs make:request`, `kreftjs make:resource` and `kreftjs make:policy`.
1253
+ Generate them with `kreft make:request`, `kreft make:resource` and `kreft make:policy`.
1237
1254
 
1238
1255
  ### Passing data from controllers to pages
1239
1256
 
@@ -1362,14 +1379,14 @@ await User.factory().count(10).has(Post.factory().count(3), 'posts').create()
1362
1379
 
1363
1380
  | Command | What it does |
1364
1381
  |---|---|
1365
- | `kreftjs migrate` | Runs the new migrations (`kreftjs dev` does this by itself). |
1366
- | `kreftjs migrate:rollback` | Undoes the last batch (`--step 2` for the last two). |
1367
- | `kreftjs migrate:fresh --seed` | Drops every table, migrates again, then seeds. |
1368
- | `kreftjs migrate:status` | Which migrations ran. |
1369
- | `kreftjs db:seed` | Runs `DatabaseSeeder` (`--class PostSeeder` for another). |
1370
- | `kreftjs make:model Post -mfsc` | A model plus migration (`-m`), factory (`-f`), seeder (`-s`), controller (`-c`), page (`-p`), route (`-r`). |
1371
- | `kreftjs make:migration create_posts_table` | `add_x_to_posts_table` makes a `schema.table` one. |
1372
- | `kreftjs make:seeder`, `kreftjs make:middleware` | The files, in the right folders. |
1382
+ | `kreft migrate` | Runs the new migrations (`kreft dev` does this by itself). |
1383
+ | `kreft migrate:rollback` | Undoes the last batch (`--step 2` for the last two). |
1384
+ | `kreft migrate:fresh --seed` | Drops every table, migrates again, then seeds. |
1385
+ | `kreft migrate:status` | Which migrations ran. |
1386
+ | `kreft db:seed` | Runs `DatabaseSeeder` (`--class PostSeeder` for another). |
1387
+ | `kreft make:model Post -mfsc` | A model plus migration (`-m`), factory (`-f`), seeder (`-s`), controller (`-c`), page (`-p`), route (`-r`). |
1388
+ | `kreft make:migration create_posts_table` | `add_x_to_posts_table` makes a `schema.table` one. |
1389
+ | `kreft make:seeder`, `kreft make:middleware` | The files, in the right folders. |
1373
1390
 
1374
1391
  > [!NOTE]
1375
1392
  > `migrate:fresh` and `db:wipe` destroy data. They are meant for development databases only.
@@ -1434,7 +1451,7 @@ await Mail.send({ to, subject, text }) // printed in the terminal until MAIL_U
1434
1451
 
1435
1452
  ### Admin users
1436
1453
 
1437
- An admin is a user whose `is_admin` column is true. The test user is one; give the rights to others on the Users page, or with `kreftjs make:admin you@example.com`. Use `Route.middleware(['auth', 'admin'])` for admin-only routes.
1454
+ An admin is a user whose `is_admin` column is true. The test user is one; give the rights to others on the Users page, or with `kreft make:admin you@example.com`. Use `Route.middleware(['auth', 'admin'])` for admin-only routes.
1438
1455
 
1439
1456
  ## Middleware
1440
1457
 
@@ -1501,7 +1518,7 @@ await SendWelcome.dispatch(user).delay(60).onQueue('mail')
1501
1518
  > [!WARNING]
1502
1519
  > `dispatch` sends the job when you `await` it (or call `.then`). Calling it and forgetting the `await` sends nothing.
1503
1520
 
1504
- Queued jobs, listeners, mail and notifications run in the background. `kreftjs dev` and `kreftjs serve` work through the `jobs` table every second. Control workers with `kreftjs queue:work`, `queue:failed`, `queue:retry all`, `queue:flush`. Choose the driver with `QUEUE_CONNECTION` (`database`, `redis`, `sync`).
1521
+ Queued jobs, listeners, mail and notifications run in the background. `kreft dev` and `kreft serve` work through the `jobs` table every second. Control workers with `kreft queue:work`, `queue:failed`, `queue:retry all`, `queue:flush`. Choose the driver with `QUEUE_CONNECTION` (`database`, `redis`, `sync`).
1505
1522
 
1506
1523
  ### Uploads
1507
1524
 
@@ -1518,7 +1535,7 @@ Schedule.job(new SendDailyReport()).weekdays().at('08:00')
1518
1535
  Schedule.command('send:report Daily').hourly()
1519
1536
  ```
1520
1537
 
1521
- `kreftjs dev` and `kreftjs serve` check the schedule every minute. Set `SCHEDULER=off` to run it from cron with `kreftjs schedule:run`; `kreftjs schedule:list` shows what is planned.
1538
+ `kreft dev` and `kreft serve` check the schedule every minute. Set `SCHEDULER=off` to run it from cron with `kreft schedule:run`; `kreft schedule:list` shows what is planned.
1522
1539
 
1523
1540
  ### Redis
1524
1541
 
@@ -1612,27 +1629,27 @@ test('a post can be created and found', async () => {
1612
1629
 
1613
1630
  To test a whole project's tables, run its real migrations instead of building the schema by hand: `migrator.migrate(db, 'backend/database/migrations')`.
1614
1631
 
1615
- Component pages for the browser live in `frontend/tests/` and are opened with `kreftjs dev`.
1632
+ Component pages for the browser live in `frontend/tests/` and are opened with `kreft dev`.
1616
1633
 
1617
1634
  # Tooling
1618
1635
 
1619
1636
  ## Command line
1620
1637
 
1621
- Run `kreftjs list` to see every command your installed version has, and `kreftjs help` for the options of the main ones.
1638
+ Run `kreft list` to see every command your installed version has, and `kreft help` for the options of the main ones.
1622
1639
 
1623
1640
  ### The main commands
1624
1641
 
1625
1642
  | Command | What it does |
1626
1643
  |---|---|
1627
- | `kreftjs new my-app` | Makes a project (`--js`, `--ts`, `--db sqlite`, `--ui tailwind`, `--no-auth`). |
1628
- | `kreftjs dev` | Development server with hot reload (`--port`, `--host`, `--db`, `--api`, `--server`, `--backend`, `--seed`, `--no-hot`, `--gc`). |
1629
- | `kreftjs build` | Compiles the app into plain files in `dist/` (`--out`, `--base`, `--prerender`). |
1630
- | `kreftjs serve [dist]` | Runs a built app for real users. Answers everyone, serves only the tables you list. |
1631
- | `kreftjs update` | Updates npm packages and refreshes `kreftjs.js` (`--core`, `--npm`, `--latest`, `--check`). |
1632
- | `kreftjs add <package>` | A safer `npm install`. See [Packages](#packages). |
1633
- | `kreftjs about`, `kreftjs env`, `kreftjs log`, `kreftjs tinker` | Versions and folders, environment, logs, a console with your models (`await User.count()`). |
1634
- | `kreftjs down --secret=x` / `kreftjs up` | Maintenance mode: visitors get `503`, and `/x` lets you in. |
1635
- | `kreftjs vscode` | Installs colors, snippets and folding for `.kreftjs` files in VS Code, Cursor and VSCodium. |
1644
+ | `kreft new my-app` | Makes a project (`--js`, `--ts`, `--db sqlite`, `--ui tailwind`, `--no-auth`). |
1645
+ | `kreft dev` | Development server with hot reload (`--port`, `--host`, `--db`, `--api`, `--server`, `--backend`, `--seed`, `--no-hot`, `--gc`). |
1646
+ | `kreft build` | Compiles the app into plain files in `dist/` (`--out`, `--base`, `--prerender`). |
1647
+ | `kreft serve [dist]` | Runs a built app for real users. Answers everyone, serves only the tables you list. |
1648
+ | `kreft update` | Updates npm packages and refreshes `kreftjs.js` (`--core`, `--npm`, `--latest`, `--check`). |
1649
+ | `kreft add <package>` | A safer `npm install`. See [Packages](#packages). |
1650
+ | `kreft about`, `kreft env`, `kreft log`, `kreft tinker` | Versions and folders, environment, logs, a console with your models (`await User.count()`). |
1651
+ | `kreft down --secret=x` / `kreft up` | Maintenance mode: visitors get `503`, and `/x` lets you in. |
1652
+ | `kreft vscode` | Installs colors, snippets and folding for `.kreftjs` files in VS Code, Cursor and VSCodium. |
1636
1653
 
1637
1654
  ### Generators and database
1638
1655
 
@@ -1645,20 +1662,20 @@ Run `kreftjs list` to see every command your installed version has, and `kreftjs
1645
1662
  | `schedule:` | `run`, `work`, `list` |
1646
1663
  | Others | `route:list`, `cache:clear`, `storage:link`, `key:generate`, `event:list`, `log:clear` |
1647
1664
 
1648
- `kreftjs dev --seed` seeds a brand-new database the first time. `kreftjs key:generate` writes a 256-bit `APP_KEY` into `.env` (`--show` prints it instead).
1665
+ `kreft dev --seed` seeds a brand-new database the first time. `kreft key:generate` writes a 256-bit `APP_KEY` into `.env` (`--show` prints it instead).
1649
1666
 
1650
1667
  ### Development server safety
1651
1668
 
1652
- - `kreftjs dev` answers only this computer (`127.0.0.1`) and only requests whose `Host` is a local name (`localhost`, `127.0.0.1`, `::1`, `*.localhost`). This stops DNS-rebinding attacks, where a web page tries to reach your dev server through its own domain name.
1669
+ - `kreft dev` answers only this computer (`127.0.0.1`) and only requests whose `Host` is a local name (`localhost`, `127.0.0.1`, `::1`, `*.localhost`). This stops DNS-rebinding attacks, where a web page tries to reach your dev server through its own domain name.
1653
1670
  - To reach it through a tunnel or another name, set `KREFT_ALLOWED_HOSTS=my-tunnel.example`. To share it on your network, use `--host 0.0.0.0`.
1654
1671
  - Requests that change data in `--api` or `--db` mode are refused when they come from another web site (a browser `Origin` that is not local).
1655
- - **Moving or deleting the project folder.** The operating system cannot refuse a delete, so the server says so after it happens: if the project folder is deleted or moved to the Trash while `kreftjs dev` or `kreftjs serve` runs, it stops at once with a message. Any `kreftjs` command started from a deleted folder or one in the Trash refuses to run. Stop the server with <kbd>Ctrl</kbd>+<kbd>C</kbd> before you move or delete a project.
1672
+ - **Moving or deleting the project folder.** The operating system cannot refuse a delete, so the server says so after it happens: if the project folder is deleted or moved to the Trash while `kreft dev` or `kreft serve` runs, it stops at once with a message. Any `kreftjs` command started from a deleted folder or one in the Trash refuses to run. Stop the server with <kbd>Ctrl</kbd>+<kbd>C</kbd> before you move or delete a project.
1656
1673
 
1657
1674
  ## Developer tools
1658
1675
 
1659
1676
  Everything here comes with Kreft. Nothing else to install.
1660
1677
 
1661
- **Hot reload.** While `kreftjs dev` runs, save a `.kreftjs` file and only that component is swapped; its state stays. A `.css` file is reloaded without a page refresh, and an error shows an overlay with the file and line.
1678
+ **Hot reload.** While `kreft dev` runs, save a `.kreftjs` file and only that component is swapped; its state stays. A `.css` file is reloaded without a page refresh, and an error shows an overlay with the file and line.
1662
1679
 
1663
1680
  **Kreft DevTools.** The **S** button in the corner (or <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>) opens a panel:
1664
1681
 
@@ -1669,9 +1686,9 @@ Everything here comes with Kreft. Nothing else to install.
1669
1686
  | Route | The current route and every route, with a button to go there. |
1670
1687
  | Timeline | Store actions and bus messages as they happen. |
1671
1688
 
1672
- The button and the panel only exist under `kreftjs dev`; built apps never include them.
1689
+ The button and the panel only exist under `kreft dev`; built apps never include them.
1673
1690
 
1674
- **Types.** `kreftjs.d.ts` describes everything in `Kreft`, so TypeScript and your editor know it. `kreftjs new` copies it into new projects, and `kreftjs update --core` refreshes it.
1691
+ **Types.** `kreftjs.d.ts` describes everything in `Kreft`, so TypeScript and your editor know it. `kreft new` copies it into new projects, and `kreft update --core` refreshes it.
1675
1692
 
1676
1693
  ### Error monitor
1677
1694
 
@@ -1679,7 +1696,7 @@ In development, an uncaught error on the server shows an interactive page instea
1679
1696
 
1680
1697
  - A stack explorer that hides vendor frames and highlights yours.
1681
1698
  - A source preview around the failing line.
1682
- - A suggestion engine for common mistakes (a method typo on a model, reading a property of `undefined`, a missing table that needs `kreftjs migrate`).
1699
+ - A suggestion engine for common mistakes (a method typo on a model, reading a property of `undefined`, a missing table that needs `kreft migrate`).
1683
1700
  - The request: method, URL, route and query values, body, headers and client address. Passwords, tokens, cookies and CSRF values are masked.
1684
1701
  - Copy the error as Markdown for an issue, or as JSON.
1685
1702
 
@@ -1698,11 +1715,11 @@ state caught = null
1698
1715
 
1699
1716
  ## Build and deploy
1700
1717
 
1701
- `kreftjs build` compiles your app ahead of time:
1718
+ `kreft build` compiles your app ahead of time:
1702
1719
 
1703
1720
  ```bash
1704
- npm run build # or: kreftjs build
1705
- npm run preview # check the result: kreftjs dev dist
1721
+ npm run build # or: kreft build
1722
+ npm run preview # check the result: kreft dev dist
1706
1723
  ```
1707
1724
 
1708
1725
  | File | What it is |
@@ -1720,21 +1737,21 @@ What you get:
1720
1737
  - **A strict Content-Security-Policy works.** Every expression becomes a real function, so the built app never uses `eval` or `new Function`.
1721
1738
  - **Errors before you deploy.** A mistake in any `.kreftjs` file stops the build and names the file and line.
1722
1739
 
1723
- Options: `kreftjs build ./site --out public` builds another folder, and `--base /` changes `<base href>`. Upload the output folder to any static host.
1740
+ Options: `kreft build ./site --out public` builds another folder, and `--base /` changes `<base href>`. Upload the output folder to any static host.
1724
1741
 
1725
1742
  ### Ready HTML for every page: `--prerender`
1726
1743
 
1727
1744
  ```bash
1728
1745
  npm i -D jsdom # once per project
1729
- kreftjs build --prerender # every route without :params
1730
- kreftjs build --prerender /users/1,/users/2 # and these addresses too
1746
+ kreft build --prerender # every route without :params
1747
+ kreft build --prerender /users/1,/users/2 # and these addresses too
1731
1748
  ```
1732
1749
 
1733
1750
  Each page is opened in a simulated browser, its data loaded, and the result saved as `dist/<page>/index.html`, so visitors and search engines get finished HTML.
1734
1751
 
1735
1752
  The tags a page sets with `.seo({...})` or `meta` (description, canonical, Open Graph, Twitter, `hreflang`, JSON-LD, `lang` and `dir`) are saved in the page's HTML too, so link previews and crawlers that don't run JavaScript see them. A canonical written in `index.html` is kept for the home page only. A page where the app shows its error page is skipped.
1736
1753
 
1737
- Pages that come from your data (`/posts/:slug`) need their addresses: `kreftjs build --prerender --urls urls.js`. The file is `urls.json` (a list), `urls.txt` (one address per line), or `urls.js` (a list, or an async function that returns it).
1754
+ Pages that come from your data (`/posts/:slug`) need their addresses: `kreft build --prerender --urls urls.js`. The file is `urls.json` (a list), `urls.txt` (one address per line), or `urls.js` (a list, or an async function that returns it).
1738
1755
 
1739
1756
  ### SEO for pages from your database: `backend/routes/seo.js`
1740
1757
 
@@ -1757,32 +1774,32 @@ module.exports = {
1757
1774
  alternates: { en: `https://example.com/posts/${slug}`, ar: `https://example.com/ar/posts/${slug}` },
1758
1775
  }
1759
1776
  },
1760
- // the addresses of your data pages, for `kreftjs sitemap`: '/path' or { path, lastmod }
1777
+ // the addresses of your data pages, for `kreft sitemap`: '/path' or { path, lastmod }
1761
1778
  urls: async () => (await Post.all()).map((p) => ({ path: '/posts/' + p.slug, lastmod: p.updated_at })),
1762
1779
  }
1763
1780
  ```
1764
1781
 
1765
- `kreftjs dev` and `kreftjs serve` answer a page request with `index.html` plus the tags of the first matching address (`:param` and a trailing `/*` work). Set `APP_URL` and each page also gets its `canonical`. An address that isn't listed is the normal page. The browser keeps these tags until the first navigation, then the router's own tags take over.
1782
+ `kreft dev` and `kreft serve` answer a page request with `index.html` plus the tags of the first matching address (`:param` and a trailing `/*` work). Set `APP_URL` and each page also gets its `canonical`. An address that isn't listed is the normal page. The browser keeps these tags until the first navigation, then the router's own tags take over.
1766
1783
 
1767
1784
  ### Whole pages for crawlers
1768
1785
 
1769
- A crawler or link preview (Googlebot, Bingbot, WhatsApp, Facebook, X, Slack, Telegram …) that doesn't run JavaScript would see an empty `<div id="app">`. For these visitors `kreftjs dev` and `kreftjs serve` open the page in the same simulated browser as `--prerender`, wait until its data has loaded, and answer with the page already drawn. If the app shows its `errors/404.kreftjs` page, the answer has status 404. A page that `kreftjs build --prerender` already drew is sent as it is. Everyone else gets the normal page.
1786
+ A crawler or link preview (Googlebot, Bingbot, WhatsApp, Facebook, X, Slack, Telegram …) that doesn't run JavaScript would see an empty `<div id="app">`. For these visitors `kreft dev` and `kreft serve` open the page in the same simulated browser as `--prerender`, wait until its data has loaded, and answer with the page already drawn. If the app shows its `errors/404.kreftjs` page, the answer has status 404. A page that `kreft build --prerender` already drew is sent as it is. Everyone else gets the normal page.
1770
1787
 
1771
1788
  ```bash
1772
1789
  npm i -D jsdom # once per project
1773
1790
  KREFT_SSR=bots # default: crawlers and link previews only
1774
1791
  KREFT_SSR=all # every visitor
1775
1792
  KREFT_SSR=off # never
1776
- KREFT_SSR_TTL=300 # seconds a drawn page is kept (kreftjs dev never keeps them)
1793
+ KREFT_SSR_TTL=300 # seconds a drawn page is kept (kreft dev never keeps them)
1777
1794
  ```
1778
1795
 
1779
1796
  At most two pages are drawn at a time; the other crawlers wait for their turn (up to 15 seconds, 20 at once), and the same address asked twice is drawn once. A page that takes longer than 15 seconds, fails, or is not a page of the app is not tried again for 30 seconds, and the normal page is sent meanwhile, as it is when jsdom is missing. The query string is part of the address (`/search?q=sofa` is its own page). Images, styles and fonts from other sites are not downloaded while drawing, scripts are. Responses carry `Vary: User-Agent` and the same security headers as every other page. The simulated browser introduces itself with a secret `User-Agent` that changes on every start, so it is never drawn again.
1780
1797
 
1781
- ### Sitemap and robots.txt: `kreftjs sitemap`
1798
+ ### Sitemap and robots.txt: `kreft sitemap`
1782
1799
 
1783
1800
  ```bash
1784
- kreftjs sitemap --url https://example.com # public/sitemap.xml and public/robots.txt
1785
- kreftjs sitemap --url https://example.com --urls urls.js # and the addresses in that file
1801
+ kreft sitemap --url https://example.com # public/sitemap.xml and public/robots.txt
1802
+ kreft sitemap --url https://example.com --urls urls.js # and the addresses in that file
1786
1803
  ```
1787
1804
 
1788
1805
  It lists the routes of `Kreftjs.router({ routes })` in `index.html` and `routes/web.kreftjs`, skipping redirects and patterns like `/posts/:id`, plus the `urls` of `backend/routes/seo.js` and `--urls`. A `lastmod` is written only when you give one (a database date such as `2026-01-02 10:00:00` becomes `2026-01-02`). A route can list `alternates: { en: '/about', ar: '/ar/about' }` for `xhtml:link` entries.
@@ -1790,7 +1807,7 @@ It lists the routes of `Kreftjs.router({ routes })` in `index.html` and `routes/
1790
1807
  ### Deploying the backend
1791
1808
 
1792
1809
  ```bash
1793
- NODE_ENV=production kreftjs serve dist
1810
+ NODE_ENV=production kreft serve dist
1794
1811
  ```
1795
1812
 
1796
1813
  Before you do, work through the [Production checklist](#production-checklist).
@@ -1800,7 +1817,7 @@ Before you do, work through the [Production checklist](#production-checklist).
1800
1817
  TypeScript works in the browser (`.kreftjs` files and `.ts` modules) and on the server (`routes/api.ts`, `app/**/*.ts`, migrations, seeders).
1801
1818
 
1802
1819
  ```bash
1803
- kreftjs new my-app --ts
1820
+ kreft new my-app --ts
1804
1821
  ```
1805
1822
 
1806
1823
  Inside a `.kreftjs` file you can write `interface`, `type`, `enum`, `import type`, and typed `prop`, `state`, `derive` and `saved`. `kreftjs make:*` writes `.ts` files when the project has a `tsconfig.json` (or with `--ts`; `--js` forces JavaScript).
@@ -1815,10 +1832,10 @@ Execution needs no setup: Kreft uses `esbuild` if installed, otherwise Node's bu
1815
1832
  **Vite.** If your team prefers the Vite ecosystem, Kreft has a plugin that compiles `.kreftjs` files on the fly:
1816
1833
 
1817
1834
  ```bash
1818
- kreftjs vite:init # writes vite.config.js with the Kreft plugin
1819
- kreftjs vite:dev # Vite dev server with the backend API proxied
1820
- kreftjs vite:build # optimised bundle with code splitting
1821
- kreftjs vite:preview
1835
+ kreft vite:init # writes vite.config.js with the Kreft plugin
1836
+ kreft vite:dev # Vite dev server with the backend API proxied
1837
+ kreft vite:build # optimised bundle with code splitting
1838
+ kreft vite:preview
1822
1839
  ```
1823
1840
 
1824
1841
  **Electron.** Turn the same app into a desktop application. See [Desktop apps with Electron](#desktop-apps-with-electron) below.
@@ -1830,16 +1847,16 @@ Kreft can package your app as a desktop application for Windows, macOS and Linux
1830
1847
  ### Quick start
1831
1848
 
1832
1849
  ```bash
1833
- kreftjs new my-app --electron # a new app with desktop support
1850
+ kreft new my-app --electron # a new app with desktop support
1834
1851
  cd my-app && npm install
1835
- kreftjs electron:dev # dev server plus a desktop window, with hot reload
1836
- kreftjs electron:build # an installer in dist-electron/
1852
+ kreft electron:dev # dev server plus a desktop window, with hot reload
1853
+ kreft electron:build # an installer in dist-electron/
1837
1854
  ```
1838
1855
 
1839
1856
  Add desktop support to an existing app instead:
1840
1857
 
1841
1858
  ```bash
1842
- kreftjs electron:init # alias: kreftjs make:electron
1859
+ kreft electron:init # alias: kreft make:electron
1843
1860
  npm install # installs electron and electron-builder
1844
1861
  ```
1845
1862
 
@@ -1847,11 +1864,11 @@ npm install # installs electron and electron-builder
1847
1864
 
1848
1865
  | Command | What it does |
1849
1866
  |---|---|
1850
- | `kreftjs electron:init` | Writes `electron/main.js` and `electron/preload.js` and adds the scripts, the `electron` and `electron-builder` dev dependencies and a `build` block to `package.json`. Files that already exist are never overwritten. It also removes the Google Fonts links from `index.html`, so the app starts without a network. |
1851
- | `kreftjs electron:dev` | Starts `kreftjs dev` and opens a window on it. Closing the window stops the server. Flags after the command go to the dev server. |
1852
- | `kreftjs electron:build` | Runs `kreftjs build --base ./`, then `electron-builder`. |
1867
+ | `kreft electron:init` | Writes `electron/main.js` and `electron/preload.js` and adds the scripts, the `electron` and `electron-builder` dev dependencies and a `build` block to `package.json`. Files that already exist are never overwritten. It also removes the Google Fonts links from `index.html`, so the app starts without a network. |
1868
+ | `kreft electron:dev` | Starts `kreft dev` and opens a window on it. Closing the window stops the server. Flags after the command go to the dev server. |
1869
+ | `kreft electron:build` | Runs `kreft build --base ./`, then `electron-builder`. |
1853
1870
 
1854
- `kreftjs electron` is the same as `kreftjs electron:dev`. If the `electron/` folder is missing, both commands create it first.
1871
+ `kreft electron` is the same as `kreft electron:dev`. If the `electron/` folder is missing, both commands create it first.
1855
1872
 
1856
1873
  ### Project layout
1857
1874
 
@@ -1868,7 +1885,7 @@ my-app/
1868
1885
  ### How it runs
1869
1886
 
1870
1887
  - **Development.** The window loads `http://localhost:8000` (change it with `PORT`). Hot reload, the DevTools button and the error overlay work as in the browser.
1871
- - **Packaged.** The window loads `dist/index.html` from disk. That is a static build, so the Kreft backend (`routes/`, the database, `kreftjs serve`) is **not** inside the app. Point the API client at a server you host:
1888
+ - **Packaged.** The window loads `dist/index.html` from disk. That is a static build, so the Kreft backend (`routes/`, the database, `kreft serve`) is **not** inside the app. Point the API client at a server you host:
1872
1889
 
1873
1890
  ```js
1874
1891
  const api = Kreftjs.api.create({ base: 'https://api.example.com' })
@@ -1927,10 +1944,10 @@ Expose one narrow function per task. Never pass a path or a command from a page
1927
1944
  They are hidden by default. Open them with a flag or an environment variable:
1928
1945
 
1929
1946
  ```bash
1930
- kreftjs electron:dev --devtools # right side
1931
- kreftjs electron:dev --devtools=bottom # bottom, left or detach
1932
- kreftjs electron:dev --no-devtools
1933
- ELECTRON_DEVTOOLS=bottom kreftjs electron:dev
1947
+ kreft electron:dev --devtools # right side
1948
+ kreft electron:dev --devtools=bottom # bottom, left or detach
1949
+ kreft electron:dev --no-devtools
1950
+ ELECTRON_DEVTOOLS=bottom kreft electron:dev
1934
1951
  ```
1935
1952
 
1936
1953
  In development, F12 or Ctrl+Shift+I toggles them.
@@ -1962,23 +1979,23 @@ Do not turn these off to make something work. Add a bridge function instead.
1962
1979
 
1963
1980
  | Problem | Fix |
1964
1981
  |---|---|
1965
- | `Electron is not installed locally` | `kreftjs add -D electron` |
1966
- | `electron-builder is not installed` | `kreftjs add -D electron-builder` |
1982
+ | `Electron is not installed locally` | `kreft add -D electron` |
1983
+ | `electron-builder is not installed` | `kreft add -D electron-builder` |
1967
1984
  | A white window in the packaged app | Run `electron:build` again; the build must use `--base ./`. Check that `dist/index.html` exists. |
1968
1985
  | API calls fail in the packaged app | The backend is not bundled. Set an absolute `base` for the API client (see above). |
1969
1986
  | The window opens before the server is ready | It waits up to 15 seconds. Check the terminal for a dev server error. |
1970
- | Port 8000 is taken | Run with `PORT=3000 kreftjs electron:dev`. |
1987
+ | Port 8000 is taken | Run with `PORT=3000 kreft electron:dev`. |
1971
1988
 
1972
1989
  ## Packages
1973
1990
 
1974
- `kreftjs add` is a safer `npm install`:
1991
+ `kreft add` is a safer `npm install`:
1975
1992
 
1976
1993
  ```bash
1977
- kreftjs add pg mysql2 # install packages
1978
- kreftjs add -D vitest # a development dependency
1979
- kreftjs add --dry-run some-package # inspect without installing
1980
- kreftjs add --allow-scripts better-sqlite3 # allow build scripts for a trusted native package
1981
- kreftjs add --force dotenv # ignore a warning
1994
+ kreft add pg mysql2 # install packages
1995
+ kreft add -D vitest # a development dependency
1996
+ kreft add --dry-run some-package # inspect without installing
1997
+ kreft add --allow-scripts better-sqlite3 # allow build scripts for a trusted native package
1998
+ kreft add --force dotenv # ignore a warning
1982
1999
  ```
1983
2000
 
1984
2001
  What it checks before and after installing:
@@ -2005,7 +2022,7 @@ Kreft includes a Model Context Protocol server, so an AI coding agent can see yo
2005
2022
  ### Local use (stdio)
2006
2023
 
2007
2024
  ```bash
2008
- kreftjs mcp
2025
+ kreft mcp
2009
2026
  ```
2010
2027
 
2011
2028
  ```json
@@ -2018,7 +2035,7 @@ kreftjs mcp
2018
2035
 
2019
2036
  ### Over HTTP
2020
2037
 
2021
- `kreftjs dev` and `kreftjs serve` also answer at `/mcp`. Set a token and send it:
2038
+ `kreft dev` and `kreft serve` also answer at `/mcp`. Set a token and send it:
2022
2039
 
2023
2040
  ```env
2024
2041
  MCP_TOKEN=a-long-random-secret
@@ -2053,7 +2070,7 @@ Kreft is built so the safe thing is the default. This chapter lists what is prot
2053
2070
 
2054
2071
  - **Escaped views.** Everything in `{ }`, `k-text` and attributes is shown as text. `<script>` in a user's bio is only text.
2055
2072
  - **`k-html` is cleaned**, not trusted. Kreft parses the HTML the way the browser does, in a document that runs nothing, then removes scripts, frames, forms, SVG and MathML, every `on…` attribute, `srcdoc`, and addresses that start with `javascript:` or an unsafe `data:`. Even so, bind only HTML you trust or that the server already cleaned.
2056
- - **A strict Content-Security-Policy works** with built apps. `kreftjs build` turns every expression into a function ahead of time, so there is no `eval` and no `new Function`. Without a build, views compile in the browser and a strict CSP blocks that.
2073
+ - **A strict Content-Security-Policy works** with built apps. `kreft build` turns every expression into a function ahead of time, so there is no `eval` and no `new Function`. Without a build, views compile in the browser and a strict CSP blocks that.
2057
2074
  - **Prototype pollution is blocked.** Paths and keys such as `__proto__`, `constructor` and `prototype` are ignored in views, translations and JSON bodies.
2058
2075
  - **A login cookie is HttpOnly**, so a script on your page cannot read it.
2059
2076
 
@@ -2115,18 +2132,18 @@ Files get random names. Unknown extensions are stored as `.bin`. Public files ar
2115
2132
  #### The database
2116
2133
 
2117
2134
  - Values travel as parameters. Table and column names are quoted.
2118
- - The automatic table API (`--db`) is a development tool with no login. `kreftjs serve` only serves the tables you list in `kreftjs.config.json`, with `write: false` and `hidden: [...]` where needed; hidden columns cannot be read or used to sort.
2135
+ - The automatic table API (`--db`) is a development tool with no login. `kreft serve` only serves the tables you list in `kreftjs.config.json`, with `write: false` and `hidden: [...]` where needed; hidden columns cannot be read or used to sort.
2119
2136
  - Raw SQL helpers (`whereRaw`, `selectRaw`, `orderByRaw`, `DB.raw`) are for your own SQL; pass user values in their parameter array.
2120
2137
 
2121
2138
  #### Packages
2122
2139
 
2123
- `kreftjs add` blocks install scripts, typosquats and look-alike names, flags very new packages, and pins exact versions. See [Packages](#packages).
2140
+ `kreft add` blocks install scripts, typosquats and look-alike names, flags very new packages, and pins exact versions. See [Packages](#packages).
2124
2141
 
2125
2142
  ### What stays your job
2126
2143
 
2127
2144
  - **Check access on the server.** Client route guards decide what to show, not who may read data. Every route that returns private data needs `auth` and, where it matters, `admin` or a policy.
2128
2145
  - **Never trust HTML you did not clean**, and never put secrets in `PUBLIC_` variables or localStorage.
2129
- - **Keep dependencies and Node.js up to date** (`kreftjs update`, `npm audit`).
2146
+ - **Keep dependencies and Node.js up to date** (`kreft update`, `npm audit`).
2130
2147
  - **Protect the machine.** Kreft cannot protect a database, a server or a `.env` file that others can read.
2131
2148
 
2132
2149
  ## Production checklist
@@ -2137,24 +2154,24 @@ Go through this before your first real user:
2137
2154
  |---|---|
2138
2155
  | `NODE_ENV=production` and `APP_ENV=production` | Turns off debug pages, enables HSTS and the https redirect, and makes security errors fatal. |
2139
2156
  | `APP_DEBUG=false` | Never show stack traces or source code to visitors. |
2140
- | `APP_KEY` set to a 32-byte key (`kreftjs key:generate`) | In production the app refuses to start without a key of at least 16 bytes. A random per-process key would also break sessions on restart. |
2157
+ | `APP_KEY` set to a 32-byte key (`kreft key:generate`) | In production the app refuses to start without a key of at least 16 bytes. A random per-process key would also break sessions on restart. |
2141
2158
  | `APP_URL=https://your.site` | Used for links in emails, the https redirect and secure cookies. |
2142
2159
  | `TRUSTED_PROXIES` set if you use a proxy | Otherwise every visitor shares the proxy's address and rate limits. |
2143
2160
  | A real `DATABASE_URL` and a backup plan | SQLite is fine for small apps; use MySQL or PostgreSQL for several servers. |
2144
2161
  | `CACHE_STORE=redis` or `database`, `QUEUE_CONNECTION=redis` or `database` | `memory` is per process. Account lockouts live in the cache, so they are shared between servers only with `database` or `redis`. |
2145
2162
  | `MAIL_URL` set | Otherwise emails are only printed in the terminal. |
2146
2163
  | `MCP_TOKEN` set, or MCP left off | The MCP endpoint is disabled in production without it. |
2147
- | Tables listed in `kreftjs.config.json`, or no `--db` at all | `kreftjs serve` serves only the tables you list. |
2164
+ | Tables listed in `kreftjs.config.json`, or no `--db` at all | `kreft serve` serves only the tables you list. |
2148
2165
  | No test user | Do not run `--seed` against production; delete `test@example.com` if it exists. |
2149
2166
  | HTTPS in front of the app | Cookies are `Secure` in production and on `https` URLs. |
2150
- | `npm audit` and `kreftjs update` | Fix known vulnerabilities before release. |
2167
+ | `npm audit` and `kreft update` | Fix known vulnerabilities before release. |
2151
2168
 
2152
2169
  > [!NOTE]
2153
2170
  > Kreft does not replace a security review. For regulated or high-risk systems, have the app, its infrastructure and its dependencies reviewed by someone who does that professionally.
2154
2171
 
2155
2172
  ## Known limits
2156
2173
 
2157
- - Without a build, views are compiled in the browser with `new Function`, which a strict Content-Security-Policy blocks. Use `kreftjs build` for production.
2174
+ - Without a build, views are compiled in the browser with `new Function`, which a strict Content-Security-Policy blocks. Use `kreft build` for production.
2158
2175
  - Inside a view, `<` directly followed by a letter starts a tag, so write `{a < b}` with a space.
2159
2176
  - The memory of which two-factor codes were already used, and login tickets, is kept per process. Behind several servers, a code can be replayed once on each. The per-account lockout (kept in the cache) still limits guessing.
2160
2177
  - The sanitizer removes unsafe markup; it is not a substitute for choosing carefully what HTML you show.
@@ -2174,9 +2191,9 @@ Set these in `.env` (never commit it). Variables that start with `PUBLIC_` are c
2174
2191
  | `APP_NAME`, `APP_URL` | Name and public address (used in emails, https redirects, secure cookies). |
2175
2192
  | `APP_ENV`, `NODE_ENV` | `production` turns on production behaviour (either one is enough). |
2176
2193
  | `APP_DEBUG` | `true` shows the interactive error page outside production. |
2177
- | `APP_KEY` | Encrypts sessions and signs links. Make it with `kreftjs key:generate`; required in production. |
2194
+ | `APP_KEY` | Encrypts sessions and signs links. Make it with `kreft key:generate`; required in production. |
2178
2195
  | `APP_LOCALE`, `APP_FALLBACK_LOCALE`, `APP_TIMEZONE` | Language and time zone defaults. |
2179
- | `HOST`, `PORT` | Where `kreftjs serve` listens. |
2196
+ | `HOST`, `PORT` | Where `kreft serve` listens. |
2180
2197
  | `FORCE_HTTPS` | `true` redirects plain HTTP in production. |
2181
2198
  | `MAX_BODY_KB` | Largest request body accepted. |
2182
2199
 
@@ -2189,7 +2206,7 @@ Set these in `.env` (never commit it). Variables that start with `PUBLIC_` are c
2189
2206
  | `CACHE_STORE` | `database`, `file`, `memory` or `redis`. Also `CACHE_PREFIX`, `CACHE_DEFAULT_TTL`. |
2190
2207
  | `QUEUE_CONNECTION` | `database`, `redis` or `sync`. Also `QUEUE_NAMES`, `QUEUE_WORKER`. |
2191
2208
  | `REDIS_URL`, or `REDIS_HOST` `REDIS_PORT` `REDIS_USERNAME` `REDIS_PASSWORD` `REDIS_DB` `REDIS_TLS` `REDIS_PREFIX` | Redis connection. |
2192
- | `SCHEDULER` | `off` hands scheduling to cron (`kreftjs schedule:run`). |
2209
+ | `SCHEDULER` | `off` hands scheduling to cron (`kreft schedule:run`). |
2193
2210
  | `MAX_QUERY_ROWS`, `HARD_QUERY_LIMIT` | Upper limits on rows a query may return. |
2194
2211
  | `FILESYSTEM_DISK` | `local` or `public`. |
2195
2212
 
@@ -2211,9 +2228,9 @@ Set these in `.env` (never commit it). Variables that start with `PUBLIC_` are c
2211
2228
  | Variable | Meaning |
2212
2229
  |---|---|
2213
2230
  | `TRUSTED_PROXIES`, `TRUSTED_PROXY_HOPS` | Which proxies' `X-Forwarded-For` is believed, and how many stand in front with `*`. |
2214
- | `KREFT_ALLOWED_HOSTS` | Extra host names `kreftjs dev` answers to. |
2231
+ | `KREFT_ALLOWED_HOSTS` | Extra host names `kreft dev` answers to. |
2215
2232
  | `MCP_TOKEN`, `MCP_ALLOWED_ORIGIN`, `MCP_QUERY_TIMEOUT_MS` | MCP endpoint token, one extra allowed browser origin, and the query time limit. |
2216
- | `MAIL_URL`, `MAIL_FROM` | `smtp://user:password@host:587` sends real email (needs `kreftjs add nodemailer`). |
2233
+ | `MAIL_URL`, `MAIL_FROM` | `smtp://user:password@host:587` sends real email (needs `kreft add nodemailer`). |
2217
2234
  | `LOG_LEVEL`, `LOG_CHANNEL` | `debug`, `info`, `notice`, `warning`, `error`, `critical`. |
2218
2235
  | `AUTO_GC`, `AUTO_GC_THRESHOLD_MB`, `AUTO_GC_INTERVAL_MS` | The memory watchdog. |
2219
2236
 
@@ -2282,8 +2299,8 @@ Kreft is one framework for the browser and the server. The others below each cov
2282
2299
  | `<Transition>` | `k-animate="fade"` |
2283
2300
  | Vue Router with nested routes | `Kreftjs.router()`, `<kreft-view>`, `<kreft-link>`, `children` |
2284
2301
  | Pinia | `Kreftjs.store()` + `use`, with `{ saved: true }` |
2285
- | Vite dev server | `kreftjs dev` (or `kreftjs vite:dev`) |
2286
- | Nuxt static generation | `kreftjs build --prerender` |
2302
+ | Vite dev server | `kreft dev` (or `kreft vite:dev`) |
2303
+ | Nuxt static generation | `kreft build --prerender` |
2287
2304
  | Nuxt `server/api` | `server/*.js` served at `/api/*` |
2288
2305
 
2289
2306
  ## Glossary