kreftjs 0.0.2-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.
- package/README.md +12 -12
- package/bin/add.js +14 -14
- package/bin/artisan-more.js +41 -41
- package/bin/artisan.js +41 -41
- package/bin/backend/command.js +1 -1
- package/bin/backend/factory.js +1 -1
- package/bin/backend/index.js +3 -3
- package/bin/backend/model.js +2 -2
- package/bin/backend/notifications.js +1 -1
- package/bin/backend/queue.js +2 -2
- package/bin/backend/schedule.js +2 -2
- package/bin/backend/seo-pages.js +1 -1
- package/bin/backend/storage.js +1 -1
- package/bin/backend/support.js +4 -4
- package/bin/backend/typescript.js +1 -1
- package/bin/build.js +11 -11
- package/bin/db-api.js +3 -3
- package/bin/db.js +1 -1
- package/bin/deps.js +6 -6
- package/bin/electron.js +12 -12
- package/bin/env.js +2 -2
- package/bin/guard.js +2 -2
- package/bin/kreftjs-config.js +1 -1
- package/bin/kreftjs.js +105 -109
- package/bin/layout.js +1 -1
- package/bin/no-auth.js +4 -4
- package/bin/prerender.js +4 -4
- package/bin/server-routes.js +2 -2
- package/bin/ssr.js +2 -2
- package/bin/terminal.js +1 -1
- package/bin/to-ts.js +1 -1
- package/bin/update.js +17 -17
- package/bin/urls-file.js +1 -1
- package/bin/vite.js +11 -11
- package/bin/win-spawn.js +39 -0
- package/docs/Docs.kreftjs +1 -1
- package/docs/README.md +140 -123
- package/kreftjs.d.ts +1 -1
- package/kreftjs.js +18 -18
- package/package.json +3 -4
- package/templates/app/README.md +20 -20
- package/templates/app/backend/database/migrations/0001_01_01_000000_create_users_table.js +1 -1
- package/templates/app/backend/database/migrations/0001_01_01_000002_create_jobs_table.js +1 -1
- package/templates/app/backend/database/seeders/DatabaseSeeder.js +1 -1
- package/templates/app/backend/routes/api.js +1 -1
- package/templates/app/backend/routes/console.js +2 -2
- package/templates/app/frontend/errors/ErrorMonitor.kreftjs +2 -2
- package/templates/app/frontend/index.html +1 -1
- package/templates/app/frontend/kreftjs.d.ts +1 -1
- package/templates/app/frontend/kreftjs.js +18 -18
- package/templates/app/frontend/pages/Dashboard.kreftjs +1 -1
- package/templates/app/frontend/pages/ErrorMonitor.kreftjs +1 -1
- package/templates/app/frontend/pages/Home.kreftjs +2 -2
- 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** | `
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
-
|
|
106
|
-
|
|
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 `
|
|
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 `
|
|
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
|
-
| `
|
|
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 `
|
|
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:** `
|
|
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 `
|
|
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
|
-
|
|
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
|
-
`
|
|
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
|
-
- `
|
|
227
|
-
- On macOS and Linux `
|
|
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 `
|
|
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 `
|
|
258
|
+
Install a package with `kreft add`, then import it in any `.kreftjs` file:
|
|
242
259
|
|
|
243
260
|
```bash
|
|
244
|
-
|
|
245
|
-
|
|
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
|
-
`
|
|
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 (`
|
|
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 `
|
|
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
|
-
|
|
1002
|
-
|
|
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. `
|
|
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 `
|
|
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
|
-
- `
|
|
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 `
|
|
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 `
|
|
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
|
-
| `
|
|
1366
|
-
| `
|
|
1367
|
-
| `
|
|
1368
|
-
| `
|
|
1369
|
-
| `
|
|
1370
|
-
| `
|
|
1371
|
-
| `
|
|
1372
|
-
| `
|
|
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 `
|
|
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. `
|
|
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
|
-
`
|
|
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 `
|
|
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 `
|
|
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
|
-
| `
|
|
1628
|
-
| `
|
|
1629
|
-
| `
|
|
1630
|
-
| `
|
|
1631
|
-
| `
|
|
1632
|
-
| `
|
|
1633
|
-
| `
|
|
1634
|
-
| `
|
|
1635
|
-
| `
|
|
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
|
-
`
|
|
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
|
-
- `
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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. `
|
|
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 `
|
|
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
|
-
`
|
|
1718
|
+
`kreft build` compiles your app ahead of time:
|
|
1702
1719
|
|
|
1703
1720
|
```bash
|
|
1704
|
-
npm run build # or:
|
|
1705
|
-
npm run preview # check the result:
|
|
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: `
|
|
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
|
-
|
|
1730
|
-
|
|
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: `
|
|
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 `
|
|
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
|
-
`
|
|
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 `
|
|
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 (
|
|
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: `
|
|
1798
|
+
### Sitemap and robots.txt: `kreft sitemap`
|
|
1782
1799
|
|
|
1783
1800
|
```bash
|
|
1784
|
-
|
|
1785
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
1819
|
-
|
|
1820
|
-
|
|
1821
|
-
|
|
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
|
-
|
|
1850
|
+
kreft new my-app --electron # a new app with desktop support
|
|
1834
1851
|
cd my-app && npm install
|
|
1835
|
-
|
|
1836
|
-
|
|
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
|
-
|
|
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
|
-
| `
|
|
1851
|
-
| `
|
|
1852
|
-
| `
|
|
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
|
-
`
|
|
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, `
|
|
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
|
-
|
|
1931
|
-
|
|
1932
|
-
|
|
1933
|
-
ELECTRON_DEVTOOLS=bottom
|
|
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` | `
|
|
1966
|
-
| `electron-builder is not installed` | `
|
|
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
|
|
1987
|
+
| Port 8000 is taken | Run with `PORT=3000 kreft electron:dev`. |
|
|
1971
1988
|
|
|
1972
1989
|
## Packages
|
|
1973
1990
|
|
|
1974
|
-
`
|
|
1991
|
+
`kreft add` is a safer `npm install`:
|
|
1975
1992
|
|
|
1976
1993
|
```bash
|
|
1977
|
-
|
|
1978
|
-
|
|
1979
|
-
|
|
1980
|
-
|
|
1981
|
-
|
|
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
|
-
|
|
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
|
-
`
|
|
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. `
|
|
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. `
|
|
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
|
-
`
|
|
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** (`
|
|
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 (`
|
|
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 | `
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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 (`
|
|
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 `
|
|
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 `
|
|
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 | `
|
|
2286
|
-
| Nuxt static generation | `
|
|
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
|