Optimization
In development, Strutvane reads everything fresh on every start: your config files, your routes, your event listeners. That’s what you want while you change things. In production nothing changes between deploys, so it’s faster to build those once and reuse them. Optimizing means building these production caches; clearing means throwing them away so everything is read fresh again.
One command builds them all, one clears them all:
node strut optimize # on the server, after each deploynode strut optimize:clear # back to "read everything fresh"The smallest example
Section titled “The smallest example”After deploying a new version to your server:
node strut optimizeWhat you’ll see:
✔ Cached: configuration, 15 routes, 2 listeners.To undo it (for example while you debug on the server):
node strut optimize:clear ✔ Configuration cache cleared (bootstrap/cache/config.json). ✔ Route cache cleared (bootstrap/cache/routes.json). ✔ Event cache cleared (bootstrap/cache/events.json). ✔ Application cache cleared (3 entries).Why it’s fast without caches too
Section titled “Why it’s fast without caches too”Strutvane already does a lot of work once, at start-up, instead of on every request:
- Config is read, checked and frozen once when the app boots. A typo in
.envstops the start, not a request. - Routes are compiled once, and every route is checked (middleware names, bindings, policies) before the first request.
- Controllers and middleware are built fresh per request, which is cheap and keeps requests from leaking state into each other.
In the prototype, booting an app with its config, providers and 15 routes took about 7 ms. The caches matter most for start-up time (many servers, short-lived containers, node strut commands) rather than for each request.
Where the caches live, and why they’re encrypted
Section titled “Where the caches live, and why they’re encrypted”| Cache | File | Built by |
|---|---|---|
| Configuration | bootstrap/cache/config.json |
config:cache |
| Route table | bootstrap/cache/routes.json |
route:cache |
| Event listeners | bootstrap/cache/events.json |
event:cache |
bootstrap/cache/ is git-ignored: caches belong to one deployment. Each file is encrypted and authenticated with a subkey of your APP_KEY, and stamped with the key it was made with and a fingerprint of your code. The config cache holds every secret your config reads (database passwords, API keys), so a copied bootstrap/cache is useless without the key.
A cache is ignored (and your app reads everything fresh) with a warning in the log when:
| Reason | Warning |
|---|---|
It was built with a different APP_KEY (copied from another server, or the key was rotated) |
Ignoring bootstrap/cache/config.json: it was built with a different APP_KEY. Run \node strut config:cache` (or `node strut optimize`) again.` |
It was built from another version of your code (a deploy that forgot optimize) |
… it was built from another version of the code. … |
| It was edited, truncated or damaged | … it was changed after it was written. … |
| Your routes changed since it was built | Ignoring bootstrap/cache/routes.json: the routes changed since it was built. Run \node strut route:cache` again.` |
So a stale cache can make the app slower to start, but never wrong.
Every command
Section titled “Every command”| Command | Builds or clears | Run it |
|---|---|---|
optimize / optimize:clear |
Config, routes and events in one go / every bootstrap cache plus the application cache | after each deploy / when debugging on a server |
config:cache / config:clear |
The configuration snapshot | part of optimize |
route:cache / route:clear |
The checked route table (boot can then skip the route checks) | part of optimize |
event:cache / event:clear / event:list |
The listeners discovered in app/listeners |
part of optimize; event:list to see them |
cache:clear [--store=redis] / cache:forget <key> |
The application cache (what your code stored) | when cached data is wrong or stale |
ui:clear |
Vite’s development cache and the built UI files | when the UI shows an old version |
sync |
The generated files in .strutvane/, from your migrations |
when generated files are missing or stale |
ui:sync |
Only the UI registry and new resources/ui/<table>.ui.ts files (also run by sync and migrate) |
after a merge conflict in UI files |
queue:restart / queue:clear / queue:retry <id|all> / queue:flush |
Queue workers and jobs | after each deploy (queue:restart) |
schedule:list / schedule:run / schedule:work |
The scheduler | schedule:run every minute from cron |
log:clear |
Local log files | when storage/logs/ grows too big on your machine |
storage:link / storage:prune-temp |
The public disk link / stale uploads | once per server / from the scheduler |
config:cache: the config snapshot
Section titled “config:cache: the config snapshot”node strut config:cache ✔ Configuration cached (bootstrap/cache/config.json, encrypted with APP_KEY).Builds every config/*.ts file from the environment once and saves the result, so the next start reads one snapshot instead of evaluating each file.
Watch out: after config:cache, changing .env does nothing until you run it again (or config:clear), because the snapshot holds the old values. That’s also why you don’t run it on your development machine.
route:cache: the route table
Section titled “route:cache: the route table”node strut route:cache ✔ 15 routes cached (bootstrap/cache/routes.json).Saves the compiled, already checked route table, so start-up skips compiling and checking every route. It’s only used when your live routes match it exactly; otherwise it’s ignored with a warning and the routes are checked as usual.
event:cache and event:list: listeners
Section titled “event:cache and event:list: listeners”node strut event:cachenode strut event:list ✔ 2 listeners cached (bootstrap/cache/events.json).Listeners are discovered from *.listener.ts files in app/listeners/, and only imported when their event fires. event:list prints a table of each event and its listeners (or No listeners. Add a *.listener.ts file in app/listeners.). See Events.
cache:clear and cache:forget: the application cache
Section titled “cache:clear and cache:forget: the application cache”node strut cache:clear # everything in the default storenode strut cache:clear --store=redis # one storenode strut cache:forget dashboard:stats # one key ✔ Application cache cleared: 12 entries removed from the "database" store. ✔ Removed "dashboard:stats" from the "database" store.This clears what your code stored in the cache (for example, expensive dashboard numbers). It’s different from the bootstrap caches above. See Cache.
ui:clear: the UI build
Section titled “ui:clear: the UI build”node strut ui:clearDeletes Vite’s development cache and the built UI files. Run it when the browser keeps showing an old screen after an upgrade, then start npm run dev or npm run build again. See Frontend.
sync and ui:sync: the generated files
Section titled “sync and ui:sync: the generated files”node strut syncRegenerates every machine-owned file in .strutvane/ from your migrations, without touching the database: the types and resources.json always, and the outputs of the packages you have installed (the UI registry through node strut ui:sync when @strutvane/ui is installed, chart data only when @strutvane/charts is). migrate does this for you; use sync after resolving a merge conflict in generated files. Files you own are never overwritten.
queue:restart: after every deploy
Section titled “queue:restart: after every deploy”Queue workers are long-running processes, so they keep running your old code after a deploy until they restart:
node strut queue:restartEach worker finishes its current job, then exits, and your process manager starts it again with the new code. See Queues.
The scheduler
Section titled “The scheduler”node strut schedule:list # what runs whennode strut schedule:work # development: run the scheduler in the foregroundnode strut schedule:run # production: run from cron every minuteSee Task Scheduling.
storage:link
Section titled “storage:link”node strut storage:linkCreates the link that makes the public disk reachable from the web, once per server. storage:prune-temp removes uploads that were started but never finished. See File Storage.
A deploy routine
Section titled “A deploy routine”npm ci # exact versions from package-lock.jsonnpm run build # compiled server and UI in build/node strut migrate --force # production asks for confirmation unless --forcenode strut optimize # build the production cachesnode strut queue:restart # workers pick up the new code (0.3)npm start # or let your process manager restart the appOn a platform that runs several copies of your app, run migrate with --isolated, so only one copy migrates while the others wait. When a deploy needs downtime, wrap it in maintenance mode. See Deployment.
Development, production and Docker
Section titled “Development, production and Docker”| Development | Production | |
|---|---|---|
| Caches | Don’t build them: you’d see stale config and routes | node strut optimize after each deploy |
.env changes |
Picked up on the next start | Need config:cache again (or config:clear) |
| Where commands run | With Docker, inside the app container (forwarded for you) |
On the server, or in your container’s start step |
In a production Docker image, run node strut optimize when the container starts (not while building the image): the config snapshot needs the real environment variables and APP_KEY, which only exist when the container runs.
Faster processes
Section titled “Faster processes”- The framework ships compiled JavaScript. Your app’s own files can stay TypeScript (Node strips the types), but
@strutvane/frameworkis published as JavaScript, because Node won’t strip types insidenode_modules. - Fast commands. In the prototype, a cold
node strut route:listtook 0.75 to 1.0 seconds, mostly loading TypeScript. Loading command modules only when they run is the planned fix; the target is under 300 ms (unverified until built). - Several processes per server. Node runs your code on one CPU core per process. A cluster mode,
node strut serve --workers=4, is planned to use every core (Laravel’s Octane covers a similar need). - JSON logs in production (
LOG_FORMAT=json), which log tools read without parsing text. See Logging.
Common mistakes
Section titled “Common mistakes”I changed .env on the server and nothing happened
Section titled “I changed .env on the server and nothing happened”Why: you ran config:cache (or optimize) earlier, so the app reads the snapshot, not .env.
Fix:
node strut config:cache # rebuild the snapshot with the new valuesThe log says “Ignoring bootstrap/cache/…”
Section titled “The log says “Ignoring bootstrap/cache/…””Why: the cache was built with another APP_KEY, from other code, or was changed by hand. The app ignored it and read everything fresh, so it’s working, just slower to start.
Fix: run node strut optimize again on this server, after the deploy.
I ran optimize on my laptop and now my .env changes don’t show
Section titled “I ran optimize on my laptop and now my .env changes don’t show”Why: the caches are meant for production; in development they hide your edits. Fix:
node strut optimize:clearQueue jobs still run the old code after a deploy
Section titled “Queue jobs still run the old code after a deploy”Why: workers are long-running and loaded the old code when they started.
Fix: add node strut queue:restart to your deploy steps.
The browser shows an old screen after upgrading
Section titled “The browser shows an old screen after upgrading”Why: stale built files or Vite’s cache.
Fix: node strut ui:clear, then npm run build (production) or restart npm run dev.
TypeScript errors about missing types after git pull
Section titled “TypeScript errors about missing types after git pull”Why: the generated files in .strutvane/ don’t match the migrations you pulled.
Fix: node strut migrate (if there are new migrations), or node strut sync to regenerate without touching the database.
Next steps
Section titled “Next steps”- Deployment: building and running in production.
- Maintenance Mode: pause the app during a risky deploy.
- CLI Reference: every command and option.
- Configuration: how config and
.envwork.