@inertia-node/nest-fastify 0.1.0 → 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.
Files changed (2) hide show
  1. package/README.md +240 -0
  2. package/package.json +4 -3
package/README.md ADDED
@@ -0,0 +1,240 @@
1
+ # @inertia-node/nest-fastify
2
+
3
+ NestJS adapter for Inertia.js on the Fastify platform.
4
+
5
+ `@inertia-node/nest-fastify` provides the same Inertia integration model as `@inertia-node/nest`, adapted for Nest applications running on `@nestjs/platform-fastify`.
6
+
7
+ ## Features
8
+
9
+ - Provides `InertiaModule.forRoot(...)` for Fastify-backed Nest apps.
10
+ - Provides `InertiaInterceptor` for controller response conversion.
11
+ - Provides `@Inertia(...)` and `@InertiaRenderOptions(...)` decorators.
12
+ - Provides `InertiaAuthGuard` and `InertiaGuestGuard`.
13
+ - Supports Fastify session stores through `fastifySessionAdapter()`.
14
+ - Supports shared props, lazy props, deferred props, validation errors, flash data, redirects, and SSR.
15
+ - Re-exports shared helpers from `@inertia-node/core`.
16
+
17
+ ## Installation
18
+
19
+ ```sh
20
+ pnpm add @inertia-node/nest-fastify @nestjs/common @nestjs/core @nestjs/platform-fastify fastify @fastify/session @fastify/cookie
21
+ ```
22
+
23
+ ```sh
24
+ npm install @inertia-node/nest-fastify @nestjs/common @nestjs/core @nestjs/platform-fastify fastify @fastify/session @fastify/cookie
25
+ ```
26
+
27
+ Peer dependencies:
28
+
29
+ - `@nestjs/common >=10 <12`
30
+ - `@nestjs/core >=10 <12`
31
+ - `@nestjs/platform-fastify >=10 <12`
32
+ - `fastify >=4 <6`
33
+ - `reflect-metadata >=0.1 <1`
34
+ - `rxjs >=7 <8`
35
+
36
+ ## Quick Start
37
+
38
+ ```ts
39
+ import {
40
+ Controller,
41
+ Get,
42
+ Module,
43
+ UseGuards,
44
+ UseInterceptors,
45
+ } from "@nestjs/common";
46
+ import { NestFactory } from "@nestjs/core";
47
+ import { FastifyAdapter } from "@nestjs/platform-fastify";
48
+ import fastifyCookie from "@fastify/cookie";
49
+ import fastifySession from "@fastify/session";
50
+ import {
51
+ Inertia,
52
+ InertiaAuthGuard,
53
+ InertiaGuestGuard,
54
+ InertiaInterceptor,
55
+ InertiaModule,
56
+ fastifySessionAdapter,
57
+ inertiaAuth,
58
+ } from "@inertia-node/nest-fastify";
59
+
60
+ type User = {
61
+ id: number;
62
+ name: string;
63
+ email: string;
64
+ };
65
+
66
+ async function findUser(id?: number): Promise<User | null> {
67
+ if (!id) return null;
68
+ return { id, name: "Ada Lovelace", email: "ada@example.com" };
69
+ }
70
+
71
+ @Controller()
72
+ @UseInterceptors(InertiaInterceptor)
73
+ class PageController {
74
+ @Get("/dashboard")
75
+ @UseGuards(InertiaAuthGuard)
76
+ @Inertia("Dashboard/Index")
77
+ dashboard() {
78
+ return {
79
+ stats: {
80
+ users: 42,
81
+ orders: 128,
82
+ },
83
+ };
84
+ }
85
+
86
+ @Get("/login")
87
+ @UseGuards(InertiaGuestGuard)
88
+ @Inertia("Auth/Login")
89
+ login() {
90
+ return {
91
+ title: "Sign in",
92
+ };
93
+ }
94
+ }
95
+
96
+ @Module({
97
+ imports: [
98
+ InertiaModule.forRoot({
99
+ version: "1",
100
+ session: fastifySessionAdapter(),
101
+ auth: inertiaAuth({
102
+ getUser: (req) => findUser(req.session?.get("userId")),
103
+ login: (req, user: User) => {
104
+ req.session.set("userId", user.id);
105
+ },
106
+ logout: (req) => {
107
+ req.session.set("userId", null);
108
+ },
109
+ serializeUser: (user) => ({
110
+ id: user.id,
111
+ name: user.name,
112
+ }),
113
+ redirectTo: "/login",
114
+ home: "/dashboard",
115
+ }),
116
+ share: async ({ request }) => ({
117
+ locale: request.headers["accept-language"] ?? "en",
118
+ }),
119
+ rootView: ({ page }) => `
120
+ <!doctype html>
121
+ <html>
122
+ <head>
123
+ <meta charset="utf-8" />
124
+ <script type="module" src="/src/app.tsx"></script>
125
+ </head>
126
+ <body>
127
+ <div id="app" data-page='${page}'></div>
128
+ </body>
129
+ </html>`,
130
+ }),
131
+ ],
132
+ controllers: [PageController],
133
+ })
134
+ class AppModule {}
135
+
136
+ async function bootstrap() {
137
+ const app = await NestFactory.create(AppModule, new FastifyAdapter());
138
+
139
+ await app.register(fastifyCookie);
140
+ await app.register(fastifySession, {
141
+ secret: process.env.SESSION_SECRET ?? "replace-this-with-32-characters",
142
+ cookie: {
143
+ secure: false,
144
+ },
145
+ });
146
+
147
+ await app.listen(3000);
148
+ }
149
+
150
+ void bootstrap();
151
+ ```
152
+
153
+ ## Controller Patterns
154
+
155
+ Use `@Inertia(...)` when a route maps directly to one page component:
156
+
157
+ ```ts
158
+ @Get("/settings")
159
+ @Inertia("Settings/Edit")
160
+ edit() {
161
+ return {
162
+ preferences: loadPreferences(),
163
+ };
164
+ }
165
+ ```
166
+
167
+ Use explicit helper results when the route needs to redirect or return validation errors:
168
+
169
+ ```ts
170
+ @Post("/settings")
171
+ async update() {
172
+ return Inertia.backWithErrors({
173
+ email: ["Email is required."],
174
+ });
175
+ }
176
+ ```
177
+
178
+ Supported explicit results:
179
+
180
+ - `Inertia.render(component, props?, options?)`
181
+ - `Inertia.redirect(location, status?)`
182
+ - `Inertia.location(location)`
183
+ - `Inertia.backWithErrors(errors, options?)`
184
+
185
+ ## Fastify Session Adapter
186
+
187
+ `fastifySessionAdapter()` maps Fastify sessions to the shared `SessionStore` contract:
188
+
189
+ - `get(key)`
190
+ - `set(key, value)`
191
+ - `pull(key)`
192
+ - `flash(key, value)`
193
+ - `reflash()`
194
+
195
+ Register `@fastify/cookie` and `@fastify/session` before serving routes that depend on auth, flash, or validation errors.
196
+
197
+ ## SSR
198
+
199
+ ```ts
200
+ InertiaModule.forRoot({
201
+ ssr: {
202
+ enabled: true,
203
+ url: "http://127.0.0.1:13714/render",
204
+ timeoutMs: 1500,
205
+ },
206
+ });
207
+ ```
208
+
209
+ Use `@inertia-node/ssr` to run the renderer process.
210
+
211
+ ## Exports
212
+
213
+ - `InertiaModule`
214
+ - `InertiaInterceptor`
215
+ - `InertiaAuthGuard`
216
+ - `InertiaGuestGuard`
217
+ - `Inertia`
218
+ - `InertiaRenderOptions`
219
+ - `fastifySessionAdapter`
220
+ - `InertiaService`
221
+ - `NestFastifyInertiaOptions`
222
+ - `NestFastifyInertiaAsyncOptions`
223
+ - `NestFastifyRenderOptions`
224
+ - `InertiaControllerResult`
225
+ - Re-exported core helpers such as `always`, `defer`, `merge`, `optional`, `validationError`, `inertiaAuth`, and `createInertia`
226
+
227
+ ## Troubleshooting
228
+
229
+ - If controller return values are sent as plain JSON, confirm `@UseInterceptors(InertiaInterceptor)` is applied.
230
+ - If auth always fails, confirm Fastify session plugins are registered and `session: fastifySessionAdapter()` is configured.
231
+ - If validation redirects throw, confirm a session adapter is configured.
232
+ - If SSR is silently missing, set `ssr.throwOnError: true` while debugging.
233
+
234
+ ## Documentation
235
+
236
+ - Repository: https://github.com/inertia-node/inertia-node-adapter
237
+ - Quick start: https://github.com/inertia-node/inertia-node-adapter/blob/main/docs/quickstart.md
238
+ - Auth: https://github.com/inertia-node/inertia-node-adapter/blob/main/docs/auth.md
239
+ - Sessions, flash, and validation: https://github.com/inertia-node/inertia-node-adapter/blob/main/docs/session-flash-validation.md
240
+ - SSR: https://github.com/inertia-node/inertia-node-adapter/blob/main/docs/ssr.md
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inertia-node/nest-fastify",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "NestJS Fastify adapter for Inertia.js on Node.js.",
5
5
  "license": "MIT",
6
6
  "author": "Inertia Node Adapter contributors",
@@ -33,10 +33,11 @@
33
33
  }
34
34
  },
35
35
  "files": [
36
- "dist"
36
+ "dist",
37
+ "README.md"
37
38
  ],
38
39
  "dependencies": {
39
- "@inertia-node/core": "0.1.0"
40
+ "@inertia-node/core": "0.1.1"
40
41
  },
41
42
  "peerDependencies": {
42
43
  "@nestjs/common": ">=10 <12",