aegisnode 0.0.5 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +190 -218
- package/package.json +12 -11
- package/scripts/smoke-test.js +87 -5
- package/src/cli/commands/createapp.js +4 -3
- package/src/cli/commands/doctor.js +17 -11
- package/src/cli/commands/fixapp.js +9 -4
- package/src/cli/commands/generate.js +33 -28
- package/src/cli/commands/generateloader.js +10 -4
- package/src/cli/commands/startproject.js +19 -12
- package/src/cli/index.js +16 -6
- package/src/cli/utils/apps.js +41 -34
- package/src/cli/utils/project.js +14 -6
- package/src/cli/utils/scaffolds.js +87 -31
- package/src/index.js +1 -0
- package/src/runtime/config.js +10 -10
- package/src/runtime/kernel.js +49 -32
- package/src/runtime/typescript.js +21 -0
- package/src/utils/source-files.js +78 -0
package/README.md
CHANGED
|
@@ -2,76 +2,24 @@
|
|
|
2
2
|
|
|
3
3
|

|
|
4
4
|
|
|
5
|
-
AegisNode is a modular, view-first Node.js framework for building web apps, JSON APIs, and hybrid projects
|
|
6
|
-
It gives you a structured project layout, runtime injection, CLI scaffolding, and production-ready defaults
|
|
5
|
+
AegisNode is a modular, view-first Node.js framework for building web apps, JSON APIs, and hybrid projects.
|
|
6
|
+
It gives you a structured project layout, runtime injection, CLI scaffolding, and production-ready defaults so you can start building features instead of first wiring routing, config loading, auth, uploads, and other framework glue.
|
|
7
7
|
|
|
8
8
|
AegisNode is designed for developers who want more structure than raw Express, but do not want a framework that hides the Node.js runtime behind too many abstractions.
|
|
9
|
-
It keeps the request/response model familiar while organizing the codebase around clear app boundaries
|
|
9
|
+
It keeps the request/response model familiar while organizing the codebase around clear app boundaries and reusable layers such as views, services, models, validators, subscribers, and app-local utilities.
|
|
10
10
|
|
|
11
11
|
It works well for projects that mix server-rendered pages and JSON endpoints, for teams that want a consistent project shape from the start, and for codebases that need built-in support for common backend concerns like auth, uploads, i18n, mail, maintenance mode, and environment-driven configuration.
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
Standalone HTML handbook:
|
|
24
|
-
- Open `docs/index.html` in a browser for a sidebar-based documentation view.
|
|
25
|
-
|
|
26
|
-
## How AegisNode Helps
|
|
27
|
-
|
|
28
|
-
AegisNode helps by standardizing the parts that usually consume time early in a project:
|
|
29
|
-
- project scaffolding and app generation,
|
|
30
|
-
- route and layer organization,
|
|
31
|
-
- dependency injection and shared runtime context,
|
|
32
|
-
- config loading and environment overrides,
|
|
33
|
-
- auth, upload, mail, websocket, and i18n integration,
|
|
34
|
-
- operational helpers such as health checks, maintenance mode, and project diagnostics.
|
|
35
|
-
|
|
36
|
-
This means you spend less time writing framework glue and more time writing business features.
|
|
37
|
-
|
|
38
|
-
## Why Use AegisNode
|
|
39
|
-
|
|
40
|
-
Choose AegisNode if you want a project starter that remains readable as it grows.
|
|
41
|
-
It keeps the development model simple, but adds enough structure and tooling to make larger codebases easier to navigate, extend, and maintain.
|
|
42
|
-
|
|
43
|
-
Core features:
|
|
44
|
-
|
|
45
|
-
- CLI generators (`startproject`, `createapp`, `runserver`)
|
|
46
|
-
- App scaffold repair command (`fix`)
|
|
47
|
-
- Startup entry generator (`generateloader`)
|
|
48
|
-
- Project health checker (`doctor`)
|
|
49
|
-
- Dependency updater (`updatedeps`)
|
|
50
|
-
- Maintenance mode with custom HTML responses
|
|
51
|
-
- Generators for app artifacts (`generate view|model|validator|dto|service|subscriber|route`)
|
|
52
|
-
- DI container
|
|
53
|
-
- Event system with subscribers
|
|
54
|
-
- Modular app structure
|
|
55
|
-
- SQL/NoSQL bootstrap via QueryMesh/Mongoose
|
|
56
|
-
- WebSocket bootstrap using Socket.IO
|
|
57
|
-
- Built-in file uploads with size/type limits (`route.upload`)
|
|
58
|
-
- Built-in mail transport wrapper (`mail.send`, `req.aegis.mail.send`)
|
|
59
|
-
- Centralized config and loaders
|
|
60
|
-
- Security headers via Helmet (configurable CSP) + CSRF protection for form submissions
|
|
61
|
-
- Built-in rate limiting for basic DDoS resistance
|
|
62
|
-
- Root route file `routes.js` (not `routes/` folder)
|
|
63
|
-
- Automatic default confirmation page on `/` when no custom `/` route exists
|
|
64
|
-
- App folder uses `views.js` (not `controllers/` folder)
|
|
65
|
-
- `createapp` uses file modules: `views.js`, `models.js`, `validators.js`, `routes.js`, `subscribers.js`, `services.js`, `utils.js`
|
|
66
|
-
- `createapp` also generates app tests in `apps/<app>/tests`
|
|
67
|
-
- EJS templates configurable in `settings.js` with Django-style base layout flow
|
|
68
|
-
- Built-in runtime helpers (`money`, `number`, `dateTime`, `timeElapsed`, `toObjectId`) + `jlive` bridge
|
|
69
|
-
|
|
70
|
-
`startproject` creates `app.js`, `loader.cjs`, `.env`, `settings.js`, and `routes.js` without creating any default app.
|
|
71
|
-
It does not create `public/` or `logs/`; create your own folders and set them in `settings.js`.
|
|
72
|
-
|
|
73
|
-
Environment files are loaded automatically before `settings.js` is imported.
|
|
74
|
-
Supported files:
|
|
12
|
+
|
|
13
|
+
Read this README in this order:
|
|
14
|
+
1. Quick Start: get a project created, installed, and running.
|
|
15
|
+
2. Core Concepts And App Structure: understand where code lives and how layers fit together.
|
|
16
|
+
3. Common Tasks And Feature Guides: jump to the feature you need once the basics are clear.
|
|
17
|
+
4. Full Settings Reference: use this when you already know which config block you are looking for.
|
|
18
|
+
5. Runtime Patterns And Advanced Topics: read this last for middleware, validators, subscribers, and strict-layer behavior.
|
|
19
|
+
|
|
20
|
+
If you prefer a sidebar-based handbook, open `docs/index.html` in a browser.
|
|
21
|
+
|
|
22
|
+
Environment files are loaded automatically before `settings.js` or `settings.ts` is imported:
|
|
75
23
|
- `.env`
|
|
76
24
|
- `.env.local`
|
|
77
25
|
- `.env.<NODE_ENV>`
|
|
@@ -81,191 +29,132 @@ Shell or hosting-panel environment variables win over values from `.env` files.
|
|
|
81
29
|
|
|
82
30
|
## Quick Start
|
|
83
31
|
|
|
84
|
-
|
|
32
|
+
Use this section to get a project running first. Skip to later sections only when you need a specific feature or configuration block.
|
|
33
|
+
|
|
34
|
+
### Create A Project
|
|
85
35
|
|
|
86
36
|
```bash
|
|
87
37
|
npm install -g aegisnode
|
|
88
38
|
|
|
39
|
+
mkdir blog && cd blog
|
|
89
40
|
aegisnode startproject blog
|
|
90
|
-
npm --prefix blog install
|
|
91
|
-
aegisnode runserver --project blog
|
|
92
|
-
|
|
93
|
-
aegisnode createapp users --project blog
|
|
94
|
-
aegisnode fix --app users --project blog
|
|
95
|
-
aegisnode generate view profile --app users --project blog
|
|
96
|
-
aegisnode generate route profile --app users --project blog
|
|
97
|
-
aegisnode generateloader --project blog
|
|
98
|
-
aegisnode doctor --project blog
|
|
99
|
-
aegisnode doctor --app users --project blog
|
|
100
|
-
aegisnode updatedeps --project blog
|
|
101
41
|
```
|
|
102
42
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
Run them from the project root; do not `cd` into `apps/<app>`.
|
|
107
|
-
Startup mode rules:
|
|
108
|
-
- Development (`env === development`): start with `aegisnode runserver` only.
|
|
109
|
-
- Non-development (`env !== development`): start with `node loader.cjs` (or your process manager/host pointing to `loader.cjs`).
|
|
110
|
-
- `node app.js` and `node loader.cjs` are rejected in development mode.
|
|
111
|
-
- `aegisnode runserver` is rejected outside development mode.
|
|
112
|
-
|
|
113
|
-
### Trust Proxy
|
|
114
|
-
|
|
115
|
-
If your app runs behind Nginx, Apache, Passenger, or another reverse proxy that terminates HTTPS before the Node process, set top-level `trustProxy` in `settings.js`:
|
|
43
|
+
Create and enter the project directory first. `startproject` scaffolds into the current empty directory; it does not create a nested folder for you.
|
|
44
|
+
Use plain `startproject` for a JavaScript project. Add `--typescript` once if you want the whole scaffold to use `.ts`.
|
|
45
|
+
For a TypeScript project, use `aegisnode startproject blog --typescript` inside the target folder instead.
|
|
116
46
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
This is the AegisNode equivalent of `app.set('trust proxy', 1)` in raw Express. It makes `req.secure`, `req.protocol`, client IP detection, secure cookies, and HTTPS-aware auth logic behave correctly behind the proxy.
|
|
124
|
-
|
|
125
|
-
Prefer an exact value such as `1`, `'loopback'`, or a subnet string instead of `true`.
|
|
47
|
+
`startproject` creates `app.js`, `loader.cjs`, `.env`, `settings.js`, and `routes.js` in the current directory without creating any default app.
|
|
48
|
+
Use `startproject --typescript` to generate `app.ts`, `settings.ts`, `routes.ts`, app `*.ts` files, and `tsconfig.json` instead.
|
|
49
|
+
It also creates `public/` and `templates/` so the default `staticDir` and `templates.dir` targets already exist.
|
|
50
|
+
Create any additional folders such as `logs/` yourself when needed.
|
|
126
51
|
|
|
127
|
-
###
|
|
128
|
-
|
|
129
|
-
AegisNode supports Passenger-style startup using the generated `loader.cjs`.
|
|
130
|
-
|
|
131
|
-
Passenger setup (Apache/Nginx/Plesk/cPanel/etc.):
|
|
132
|
-
1. Set **Application Root** to your project folder.
|
|
133
|
-
2. Set **Startup File** to `loader.cjs`.
|
|
134
|
-
3. Install dependencies in project root (for example: `npm install --omit=dev`).
|
|
135
|
-
4. Set environment variables (at minimum `NODE_ENV=production`; keep `PORT` managed by Passenger).
|
|
136
|
-
5. Restart the Node app from your hosting panel/service.
|
|
137
|
-
|
|
138
|
-
Plesk note: these map to **Application Root** and **Application Startup File** fields.
|
|
139
|
-
|
|
140
|
-
HTTPS note:
|
|
141
|
-
- If TLS is terminated by Passenger/Apache/Nginx, keep `https.enabled` off and set top-level `trustProxy` to `1` (or another exact proxy-hop/subnet value) so `req.secure`, secure cookies, and OAuth2 HTTPS checks work correctly.
|
|
142
|
-
- Only enable `https` in `settings.js` when Node itself should serve TLS directly.
|
|
143
|
-
|
|
144
|
-
How it works:
|
|
145
|
-
- `loader.cjs` imports `app.js`.
|
|
146
|
-
- `app.js` starts AegisNode with project root resolved from its own file location, so it works correctly under Passenger.
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
Generated routes are auto-wired into `apps/<app>/routes.js`.
|
|
150
|
-
`createapp` auto-detects the project root when run inside the project or from a parent folder containing exactly one AegisNode project.
|
|
151
|
-
After `createapp user`, `routes.js` is updated with central mapping style:
|
|
152
|
-
`route.use('/user', user);`
|
|
153
|
-
Only apps declared in `settings.apps` are allowed to load/mount. Startup fails when routes reference an undeclared app.
|
|
154
|
-
`--mount` accepts only safe path segments (`a-z`, `A-Z`, `0-9`, `_`, `-`, `:`).
|
|
155
|
-
|
|
156
|
-
By default, new app routes are API-ready:
|
|
157
|
-
- `GET /<mount>` list
|
|
158
|
-
- `POST /<mount>` create
|
|
159
|
-
- `GET /<mount>/:id` read
|
|
160
|
-
- `PUT /<mount>/:id` update
|
|
161
|
-
- `DELETE /<mount>/:id` delete
|
|
162
|
-
|
|
163
|
-
Default flow is `route -> validator -> service -> model`.
|
|
164
|
-
Default app tests generated by `createapp`:
|
|
165
|
-
- `apps/<app>/tests/models.test.js`
|
|
166
|
-
- `apps/<app>/tests/validators.test.js`
|
|
167
|
-
- `apps/<app>/tests/services.test.js`
|
|
168
|
-
- `apps/<app>/tests/routes.test.js`
|
|
169
|
-
|
|
170
|
-
Run all project tests:
|
|
52
|
+
### Install Dependencies And Run The Server
|
|
171
53
|
|
|
172
54
|
```bash
|
|
173
|
-
npm
|
|
55
|
+
npm install
|
|
56
|
+
aegisnode runserver
|
|
174
57
|
```
|
|
175
58
|
|
|
176
|
-
|
|
59
|
+
If you choose to stay outside the project folder, the project-level commands also accept `--project <path>`.
|
|
60
|
+
|
|
61
|
+
### Create Your First App
|
|
177
62
|
|
|
178
63
|
```bash
|
|
179
|
-
aegisnode
|
|
64
|
+
aegisnode createapp users
|
|
65
|
+
aegisnode generate view profile --app users
|
|
66
|
+
aegisnode generate route profile --app users
|
|
180
67
|
```
|
|
181
68
|
|
|
182
|
-
`
|
|
183
|
-
|
|
184
|
-
- Startup entry files (`app.js`, `loader.cjs`), with production errors when `loader.cjs` is missing
|
|
185
|
-
- App declarations vs filesystem
|
|
186
|
-
- Security baseline (`appSecret`, csrf/headers/ddos toggles)
|
|
187
|
-
- Auth safety checks (JWT secret, OAuth2 `allowHttp` in production)
|
|
188
|
-
- Template directory availability
|
|
69
|
+
`createapp` updates `settings.apps` and the root `routes.js` or `routes.ts` mapping for you.
|
|
70
|
+
It also generates default app tests under `apps/<app>/tests`.
|
|
189
71
|
|
|
190
|
-
|
|
72
|
+
### Startup Mode Rules
|
|
191
73
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
74
|
+
- Development (`env === 'development'`): start with `aegisnode runserver`.
|
|
75
|
+
- Non-development (`env !== 'development'`): start with `node loader.cjs`.
|
|
76
|
+
- `node app.js` and `node loader.cjs` are blocked in development mode.
|
|
77
|
+
- `aegisnode runserver` is blocked outside development mode.
|
|
195
78
|
|
|
196
|
-
|
|
197
|
-
- Missing `views.js`, `models.js`, `services.js`, `validators.js`, `routes.js`, `subscribers.js`, `utils.js`
|
|
198
|
-
- Missing generated test files under `apps/<app>/tests`
|
|
199
|
-
- Missing `settings.apps` declaration for that app
|
|
200
|
-
- Missing central `routes.js` import/mount when `autoMountApps` is off
|
|
79
|
+
### Project Maintenance Commands
|
|
201
80
|
|
|
202
|
-
|
|
81
|
+
Use these after the project already exists:
|
|
203
82
|
|
|
204
83
|
```bash
|
|
84
|
+
aegisnode doctor
|
|
85
|
+
aegisnode doctor --app users
|
|
205
86
|
aegisnode fix --app users
|
|
87
|
+
aegisnode generateloader
|
|
88
|
+
aegisnode updatedeps
|
|
206
89
|
```
|
|
207
90
|
|
|
208
|
-
|
|
91
|
+
What they do:
|
|
92
|
+
- `doctor`: checks project structure, startup entry files, app declarations, and security/auth basics.
|
|
93
|
+
- `doctor --app`: checks one app for missing scaffold files, tests, and registrations.
|
|
94
|
+
- `fix --app`: recreates missing app scaffold files without overwriting existing files.
|
|
95
|
+
- `generateloader`: restores `loader.cjs` and `app.js` when startup files are missing.
|
|
96
|
+
- `updatedeps`: rewrites package dependency ranges to the current npm `latest` versions and reinstalls.
|
|
209
97
|
|
|
210
|
-
|
|
98
|
+
Run project tests with:
|
|
211
99
|
|
|
212
100
|
```bash
|
|
213
|
-
|
|
101
|
+
npm test
|
|
214
102
|
```
|
|
215
103
|
|
|
216
|
-
|
|
104
|
+
### JavaScript vs TypeScript Projects
|
|
217
105
|
|
|
218
|
-
|
|
106
|
+
The project type is chosen once at `startproject` time:
|
|
107
|
+
- `aegisnode startproject blog` scaffolds a JavaScript project in the current directory
|
|
108
|
+
- `aegisnode startproject blog --typescript` scaffolds a TypeScript project in the current directory
|
|
219
109
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
110
|
+
After that, the rest of the CLI follows the project automatically:
|
|
111
|
+
- `createapp` generates `views.js` / `services.js` / `routes.js` in JavaScript projects, or `views.ts` / `services.ts` / `routes.ts` in TypeScript projects
|
|
112
|
+
- `generate` creates artifacts with the same extension as the project, for example `profile.view.js` or `profile.view.ts`
|
|
113
|
+
- `fix`, `doctor`, and `generateloader` also check and repair the matching project file type automatically
|
|
223
114
|
|
|
224
|
-
`
|
|
225
|
-
|
|
226
|
-
`install`. It skips non-registry specs such as `file:`, `workspace:`, and git/http sources.
|
|
115
|
+
`createapp`, `fix`, `generate`, `runserver`, `generateloader`, `doctor`, and `updatedeps` are project-level commands.
|
|
116
|
+
Run them from the project root; do not `cd` into `apps/<app>`.
|
|
227
117
|
|
|
228
|
-
|
|
118
|
+
## Core Concepts And App Structure
|
|
229
119
|
|
|
230
|
-
|
|
231
|
-
If that route is missing or does not respond, AegisNode renders its internal maintenance fallback view:
|
|
120
|
+
Use this section to understand the project shape before you start adding more features. The goal here is to make it clear where code belongs and what each layer is responsible for.
|
|
232
121
|
|
|
233
|
-
|
|
234
|
-
export default {
|
|
235
|
-
maintenance: {
|
|
236
|
-
enabled: true,
|
|
237
|
-
route: '/maintenance',
|
|
238
|
-
excludePaths: ['/health'],
|
|
239
|
-
retryAfter: 120,
|
|
240
|
-
},
|
|
241
|
-
};
|
|
242
|
-
```
|
|
122
|
+
### Generated Project Shape
|
|
243
123
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
route.get('/maintenance', (req, res) => {
|
|
248
|
-
res.render('maintenance', {
|
|
249
|
-
title: 'Scheduled maintenance',
|
|
250
|
-
});
|
|
251
|
-
});
|
|
252
|
-
},
|
|
253
|
-
};
|
|
254
|
-
```
|
|
124
|
+
`startproject` creates the runtime entry files and base config for you in the current directory:
|
|
125
|
+
- JavaScript projects: `app.js`, `loader.cjs`, `.env`, `settings.js`, `routes.js`
|
|
126
|
+
- TypeScript projects: `app.ts`, `loader.cjs`, `.env`, `settings.ts`, `routes.ts`, `tsconfig.json`
|
|
255
127
|
|
|
256
|
-
|
|
257
|
-
- `
|
|
258
|
-
-
|
|
259
|
-
- `
|
|
260
|
-
- `
|
|
261
|
-
- `
|
|
262
|
-
- `
|
|
128
|
+
`createapp` then adds feature modules under `apps/<app>/`:
|
|
129
|
+
- `views.js` or `views.ts`
|
|
130
|
+
- `models.js` or `models.ts`
|
|
131
|
+
- `services.js` or `services.ts`
|
|
132
|
+
- `validators.js` or `validators.ts`
|
|
133
|
+
- `routes.js` or `routes.ts`
|
|
134
|
+
- `subscribers.js` or `subscribers.ts`
|
|
135
|
+
- `utils.js` or `utils.ts`
|
|
136
|
+
- `tests/`
|
|
137
|
+
|
|
138
|
+
Other scaffold rules to know:
|
|
139
|
+
- `createapp` auto-detects the project root when you run it inside the project or from a parent folder containing exactly one AegisNode project.
|
|
140
|
+
- New apps are registered in `settings.apps` and mounted in the root `routes.js` or `routes.ts`.
|
|
141
|
+
- Only apps declared in `settings.apps` are allowed to load or mount.
|
|
142
|
+
- `--mount` accepts only safe path segments (`a-z`, `A-Z`, `0-9`, `_`, `-`, `:`).
|
|
143
|
+
- New app routes are generated in an API-ready CRUD shape by default:
|
|
144
|
+
- `GET /<mount>`
|
|
145
|
+
- `POST /<mount>`
|
|
146
|
+
- `GET /<mount>/:id`
|
|
147
|
+
- `PUT /<mount>/:id`
|
|
148
|
+
- `DELETE /<mount>/:id`
|
|
149
|
+
- Default app tests generated by `createapp` are:
|
|
150
|
+
- JavaScript projects: `apps/<app>/tests/models.test.js`, `validators.test.js`, `services.test.js`, `routes.test.js`
|
|
151
|
+
- TypeScript projects: `apps/<app>/tests/models.test.ts`, `validators.test.ts`, `services.test.ts`, `routes.test.ts`
|
|
263
152
|
|
|
264
|
-
### Generated Settings
|
|
153
|
+
### Generated Settings Shape
|
|
265
154
|
|
|
266
|
-
`startproject` generates a minimal `settings.js` and runtime defaults fill the rest.
|
|
155
|
+
`startproject` generates a minimal `settings.js` or `settings.ts`, and runtime defaults fill the rest.
|
|
267
156
|
|
|
268
|
-
Access environment values
|
|
157
|
+
Access environment values directly with `process.env` in the settings file:
|
|
269
158
|
|
|
270
159
|
```js
|
|
271
160
|
export default {
|
|
@@ -276,9 +165,9 @@ export default {
|
|
|
276
165
|
};
|
|
277
166
|
```
|
|
278
167
|
|
|
279
|
-
Injected app layers also receive `env`, so views
|
|
168
|
+
Injected app layers also receive `env`, so views, services, models, validators, controllers, subscribers, and loaders can use `env.MY_NAME` without importing `process.env`.
|
|
280
169
|
|
|
281
|
-
|
|
170
|
+
Generated shape:
|
|
282
171
|
|
|
283
172
|
```js
|
|
284
173
|
export default {
|
|
@@ -287,6 +176,13 @@ export default {
|
|
|
287
176
|
host: process.env.HOST || '0.0.0.0',
|
|
288
177
|
port: process.env.PORT ? Number(process.env.PORT) : 3000,
|
|
289
178
|
trustProxy: false,
|
|
179
|
+
staticDir: 'public',
|
|
180
|
+
templates: {
|
|
181
|
+
enabled: true,
|
|
182
|
+
engine: 'ejs',
|
|
183
|
+
dir: 'templates',
|
|
184
|
+
base: 'base',
|
|
185
|
+
},
|
|
290
186
|
security: {
|
|
291
187
|
appSecret: process.env.APP_SECRET || '<generated-at-scaffold-time>',
|
|
292
188
|
},
|
|
@@ -313,12 +209,11 @@ export default {
|
|
|
313
209
|
|
|
314
210
|
Notes:
|
|
315
211
|
- Keep `AEGIS_APPS_START/END` markers; `createapp` updates this list automatically.
|
|
316
|
-
- `startproject` writes a local `.env` with a generated `APP_SECRET` and also embeds the same generated secret in `settings.js` as a fallback.
|
|
317
|
-
-
|
|
212
|
+
- `startproject` writes a local `.env` with a generated `APP_SECRET` and also embeds the same generated secret in `settings.js` or `settings.ts` as a fallback.
|
|
213
|
+
- The scaffold already includes `staticDir: 'public'` and a default `templates` block, and it creates those directories for you.
|
|
214
|
+
- Add optional blocks only when you need them: `https`, `i18n`, `helpers`, `websocket`, `uploads`, `mail`, `auth`, `api`, `swagger`, `loaders`, `environments`, `architecture`, `security.headers/ddos/csrf`.
|
|
318
215
|
- Any section you omit uses framework defaults from `src/runtime/config.js`.
|
|
319
216
|
|
|
320
|
-
## Core Concepts And App Structure
|
|
321
|
-
|
|
322
217
|
### App File Usage Examples
|
|
323
218
|
|
|
324
219
|
Each generated app usually contains:
|
|
@@ -329,6 +224,8 @@ Each generated app usually contains:
|
|
|
329
224
|
- `apps/<app>/subscribers.js`
|
|
330
225
|
- `apps/<app>/routes.js`
|
|
331
226
|
|
|
227
|
+
If the project was created with `--typescript`, the same generated files use `.ts` instead of `.js`.
|
|
228
|
+
|
|
332
229
|
Usage by file:
|
|
333
230
|
- `views.js`: HTTP handlers (`req`, `res`, `next`). Default signature can be context-first: `handler({ service, validator, services, validators, ... }, req, res, next)`.
|
|
334
231
|
Keep `views.js` thin: prefer only the view class and its imports. Avoid defining extra local helper/utility functions in the view file. Move reusable pure logic to `utils.js` and app workflows to `services.js`.
|
|
@@ -540,6 +437,77 @@ export default {
|
|
|
540
437
|
|
|
541
438
|
## Common Tasks And Feature Guides
|
|
542
439
|
|
|
440
|
+
Use this section once the project is already running and you need a specific feature, integration, or deployment-related behavior.
|
|
441
|
+
|
|
442
|
+
### Reverse Proxies And Passenger
|
|
443
|
+
|
|
444
|
+
If HTTPS is terminated by Nginx, Apache, Passenger, or another reverse proxy before the Node process, set top-level `trustProxy` in `settings.js` or `settings.ts`:
|
|
445
|
+
|
|
446
|
+
```js
|
|
447
|
+
export default {
|
|
448
|
+
trustProxy: 1,
|
|
449
|
+
};
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
This is the AegisNode equivalent of `app.set('trust proxy', 1)` in raw Express. It makes `req.secure`, `req.protocol`, client IP detection, secure cookies, and HTTPS-aware auth logic behave correctly behind the proxy.
|
|
453
|
+
|
|
454
|
+
Prefer an exact value such as `1`, `'loopback'`, or a subnet string instead of `true`.
|
|
455
|
+
|
|
456
|
+
AegisNode also supports Passenger-style startup using the generated `loader.cjs`.
|
|
457
|
+
|
|
458
|
+
Passenger setup (Apache, Nginx, Plesk, cPanel, and similar hosts):
|
|
459
|
+
1. Set **Application Root** to your project folder.
|
|
460
|
+
2. Set **Startup File** to `loader.cjs`.
|
|
461
|
+
3. Install dependencies in the project root, for example `npm install --omit=dev`.
|
|
462
|
+
4. Set environment variables. At minimum, make sure the resolved app env is production and let Passenger manage `PORT`.
|
|
463
|
+
5. Restart the Node app from the hosting panel or service manager.
|
|
464
|
+
|
|
465
|
+
Plesk note: these map to **Application Root** and **Application Startup File** fields.
|
|
466
|
+
|
|
467
|
+
HTTPS note:
|
|
468
|
+
- If TLS is terminated by Passenger, Apache, or Nginx, keep `https.enabled` off and use `trustProxy`.
|
|
469
|
+
- Only enable `https` in `settings.js` or `settings.ts` when Node itself should serve TLS directly.
|
|
470
|
+
|
|
471
|
+
How it works:
|
|
472
|
+
- `loader.cjs` imports `app.js` in JavaScript projects or `app.ts` in TypeScript projects.
|
|
473
|
+
- `app.js` or `app.ts` starts AegisNode with project root resolved from its own file location, so the same entry works under process managers and hosting panels.
|
|
474
|
+
|
|
475
|
+
### Maintenance Mode
|
|
476
|
+
|
|
477
|
+
Enable maintenance mode in `settings.js` or `settings.ts` to serve a maintenance route with `503 Service Unavailable`.
|
|
478
|
+
If that route is missing or does not respond, AegisNode renders its internal maintenance fallback view.
|
|
479
|
+
|
|
480
|
+
```js
|
|
481
|
+
export default {
|
|
482
|
+
maintenance: {
|
|
483
|
+
enabled: true,
|
|
484
|
+
route: '/maintenance',
|
|
485
|
+
excludePaths: ['/health'],
|
|
486
|
+
retryAfter: 120,
|
|
487
|
+
},
|
|
488
|
+
};
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
```js
|
|
492
|
+
export default {
|
|
493
|
+
register(route) {
|
|
494
|
+
route.get('/maintenance', (req, res) => {
|
|
495
|
+
res.render('maintenance', {
|
|
496
|
+
title: 'Scheduled maintenance',
|
|
497
|
+
});
|
|
498
|
+
});
|
|
499
|
+
},
|
|
500
|
+
};
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
Notes:
|
|
504
|
+
- `maintenance.route` is internally rewritten, so requests like `/users` can display your maintenance page without a redirect.
|
|
505
|
+
- If `maintenance.route` is not defined, or the route does not answer, the bundled fallback view is rendered.
|
|
506
|
+
- `excludePaths` lets selected endpoints keep running during maintenance.
|
|
507
|
+
- `retryAfter` sets the HTTP `Retry-After` header.
|
|
508
|
+
- `maintenance: true` uses the built-in default maintenance page.
|
|
509
|
+
- `maintenance: '<html>...</html>'` is still accepted as a shorthand for direct custom HTML.
|
|
510
|
+
|
|
543
511
|
### File Uploads
|
|
544
512
|
|
|
545
513
|
AegisNode provides built-in upload middleware on route API as `route.upload`.
|
|
@@ -880,7 +848,7 @@ export default {
|
|
|
880
848
|
},
|
|
881
849
|
security: {
|
|
882
850
|
ddos: {
|
|
883
|
-
maxRequests:
|
|
851
|
+
maxRequests: 300,
|
|
884
852
|
},
|
|
885
853
|
},
|
|
886
854
|
environments: {
|
|
@@ -1661,6 +1629,8 @@ Then in EJS:
|
|
|
1661
1629
|
<!-- SETTINGS_REFERENCE_START -->
|
|
1662
1630
|
## Full Settings Reference
|
|
1663
1631
|
|
|
1632
|
+
Use this section as a config manual. It is intentionally reference-heavy and is easier to use after you already know which feature or runtime block you need to configure.
|
|
1633
|
+
|
|
1664
1634
|
All fields below are supported in `settings.js`. If you omit a field, AegisNode uses the runtime default.
|
|
1665
1635
|
|
|
1666
1636
|
Merge order used at startup:
|
|
@@ -1888,7 +1858,7 @@ security: {
|
|
|
1888
1858
|
| --- | --- | --- |
|
|
1889
1859
|
| `enabled` | `boolean` / `true` | Enable rate limiter. |
|
|
1890
1860
|
| `windowMs` | `number` / `60000` | Rate limit window in milliseconds. |
|
|
1891
|
-
| `maxRequests` | `number` / `
|
|
1861
|
+
| `maxRequests` | `number` / `300` | Max requests per window per key. |
|
|
1892
1862
|
| `message` | `string` / `'Too many requests, please try again later.'` | JSON error message text. |
|
|
1893
1863
|
| `statusCode` | `number` / `429` | Response status code when limited. |
|
|
1894
1864
|
| `standardHeaders` | `boolean` / `true` | Emit modern rate-limit headers. |
|
|
@@ -2176,6 +2146,8 @@ Behavior:
|
|
|
2176
2146
|
|
|
2177
2147
|
## Runtime Patterns And Advanced Topics
|
|
2178
2148
|
|
|
2149
|
+
Use this section after the basics are clear. It covers the runtime contracts that matter once you are shaping larger apps or enforcing stricter boundaries.
|
|
2150
|
+
|
|
2179
2151
|
### Middleware
|
|
2180
2152
|
|
|
2181
2153
|
Route API supports Express-style middleware chains:
|
|
@@ -2541,7 +2513,7 @@ security: {
|
|
|
2541
2513
|
ddos: {
|
|
2542
2514
|
enabled: true,
|
|
2543
2515
|
windowMs: 60000,
|
|
2544
|
-
maxRequests:
|
|
2516
|
+
maxRequests: 300,
|
|
2545
2517
|
message: 'Too many requests, please try again later.',
|
|
2546
2518
|
statusCode: 429,
|
|
2547
2519
|
standardHeaders: true,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "aegisnode",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "A view-first Node.js framework for modular web apps and JSON APIs with CLI scaffolding, runtime injection, auth, uploads, i18n, mail, and WebSocket support.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./src/index.js",
|
|
@@ -44,17 +44,18 @@
|
|
|
44
44
|
},
|
|
45
45
|
"license": "MIT",
|
|
46
46
|
"dependencies": {
|
|
47
|
-
"ejs": "^
|
|
48
|
-
"express": "^
|
|
49
|
-
"express-rate-limit": "^8.
|
|
47
|
+
"ejs": "^5.0.2",
|
|
48
|
+
"express": "^5.2.1",
|
|
49
|
+
"express-rate-limit": "^8.5.2",
|
|
50
50
|
"helmet": "^8.1.0",
|
|
51
51
|
"jlive": "^0.1.2",
|
|
52
|
-
"jsonwebtoken": "^9.0.
|
|
53
|
-
"mongoose": "^
|
|
54
|
-
"multer": "^2.1.
|
|
55
|
-
"nodemailer": "^8.0.
|
|
56
|
-
"querymesh": "^0.0
|
|
57
|
-
"socket.io": "^4.8.
|
|
58
|
-
"swagger-ui-express": "^5.0.1"
|
|
52
|
+
"jsonwebtoken": "^9.0.3",
|
|
53
|
+
"mongoose": "^9.6.2",
|
|
54
|
+
"multer": "^2.1.1",
|
|
55
|
+
"nodemailer": "^8.0.7",
|
|
56
|
+
"querymesh": "^0.1.0",
|
|
57
|
+
"socket.io": "^4.8.3",
|
|
58
|
+
"swagger-ui-express": "^5.0.1",
|
|
59
|
+
"tsx": "^4.22.0"
|
|
59
60
|
}
|
|
60
61
|
}
|