npm - @venizia/ignis-docs - Versions diffs - 0.2.0 → 0.2.1-1 - Mend

@venizia/ignis-docs 0.2.0 → 0.2.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 (174) hide show

package/README.md +14 -14
package/content/best-practices/api-usage-examples.md +39 -19
package/content/best-practices/architectural-patterns.md +24 -13
package/content/best-practices/architecture-decisions.md +29 -16
package/content/best-practices/code-style-standards/advanced-patterns.md +43 -31
package/content/best-practices/code-style-standards/constants-configuration.md +19 -4
package/content/best-practices/code-style-standards/control-flow.md +33 -1
package/content/best-practices/code-style-standards/documentation.md +28 -8
package/content/best-practices/code-style-standards/function-patterns.md +15 -4
package/content/best-practices/code-style-standards/index.md +7 -2
package/content/best-practices/code-style-standards/naming-conventions.md +27 -3
package/content/best-practices/code-style-standards/route-definitions.md +9 -5
package/content/best-practices/code-style-standards/tooling.md +14 -1
package/content/best-practices/code-style-standards/type-safety.md +39 -6
package/content/best-practices/common-pitfalls.md +59 -35
package/content/best-practices/contribution-workflow.md +8 -4
package/content/best-practices/data-modeling.md +78 -62
package/content/best-practices/deployment-strategies.md +56 -19
package/content/best-practices/error-handling.md +247 -153
package/content/best-practices/index.md +6 -0
package/content/best-practices/performance-optimization.md +26 -13
package/content/best-practices/security-guidelines.md +35 -9
package/content/best-practices/testing-strategies.md +7 -2
package/content/best-practices/troubleshooting-tips.md +27 -17
package/content/extensions/components/api-reference.md +109 -323
package/content/extensions/components/authentication/api.md +489 -602
package/content/extensions/components/authentication/errors.md +135 -498
package/content/extensions/components/authentication/index.md +89 -801
package/content/extensions/components/authentication/usage.md +231 -955
package/content/extensions/components/authorization/api.md +991 -644
package/content/extensions/components/authorization/errors.md +204 -208
package/content/extensions/components/authorization/getting-started.md +227 -0
package/content/extensions/components/authorization/index.md +88 -795
package/content/extensions/components/authorization/usage.md +219 -528
package/content/extensions/components/health-check.md +77 -243
package/content/extensions/components/index.md +24 -90
package/content/extensions/components/mail/api.md +553 -285
package/content/extensions/components/mail/errors.md +76 -62
package/content/extensions/components/mail/index.md +111 -463
package/content/extensions/components/mail/usage.md +139 -173
package/content/extensions/components/request-tracker.md +70 -173
package/content/extensions/components/socket-io/api.md +462 -785
package/content/extensions/components/socket-io/errors.md +49 -51
package/content/extensions/components/socket-io/index.md +69 -372
package/content/extensions/components/socket-io/usage.md +212 -105
package/content/extensions/components/static-asset/api.md +461 -141
package/content/extensions/components/static-asset/errors.md +121 -53
package/content/extensions/components/static-asset/index.md +84 -606
package/content/extensions/components/static-asset/usage.md +184 -299
package/content/extensions/components/template/index.md +3 -3
package/content/extensions/components/websocket/api.md +311 -404
package/content/extensions/components/websocket/errors.md +47 -56
package/content/extensions/components/websocket/index.md +75 -407
package/content/extensions/components/websocket/usage.md +120 -338
package/content/extensions/helpers/cron/index.md +52 -160
package/content/extensions/helpers/crypto/index.md +67 -480
package/content/extensions/helpers/crypto/reference.md +528 -0
package/content/extensions/helpers/env/index.md +64 -178
package/content/extensions/helpers/error/index.md +286 -196
package/content/extensions/helpers/index.md +61 -47
package/content/extensions/helpers/inversion/index.md +76 -550
package/content/extensions/helpers/inversion/reference.md +530 -0
package/content/extensions/helpers/kafka/admin.md +23 -3
package/content/extensions/helpers/kafka/compile-binary.md +83 -52
package/content/extensions/helpers/kafka/consumer.md +65 -28
package/content/extensions/helpers/kafka/examples.md +46 -253
package/content/extensions/helpers/kafka/index.md +55 -617
package/content/extensions/helpers/kafka/producer.md +156 -22
package/content/extensions/helpers/kafka/schema-registry.md +59 -79
package/content/extensions/helpers/logger/hf-logger.md +220 -0
package/content/extensions/helpers/logger/index.md +78 -552
package/content/extensions/helpers/logger/pino.md +105 -0
package/content/extensions/helpers/logger/reference.md +937 -0
package/content/extensions/helpers/network/api.md +276 -195
package/content/extensions/helpers/network/index.md +87 -524
package/content/extensions/helpers/queue/index.md +80 -897
package/content/extensions/helpers/queue/reference.md +494 -0
package/content/extensions/helpers/redis/index.md +86 -640
package/content/extensions/helpers/redis/reference.md +784 -0
package/content/extensions/helpers/secrets/index.md +136 -0
package/content/extensions/helpers/socket-io/api.md +325 -204
package/content/extensions/helpers/socket-io/index.md +79 -429
package/content/extensions/helpers/storage/api.md +584 -464
package/content/extensions/helpers/storage/index.md +80 -573
package/content/extensions/helpers/types/index.md +75 -495
package/content/extensions/helpers/types/reference.md +689 -0
package/content/extensions/helpers/uid/index.md +176 -189
package/content/extensions/helpers/websocket/api.md +366 -214
package/content/extensions/helpers/websocket/index.md +68 -503
package/content/extensions/helpers/worker-thread/index.md +62 -396
package/content/extensions/helpers/worker-thread/reference.md +428 -0
package/content/extensions/index.md +38 -39
package/content/extensions/src-details/mcp-server.md +96 -548
package/content/guides/core-concepts/persistent/datasources.md +2 -2
package/content/guides/core-concepts/persistent/index.md +5 -1
package/content/guides/core-concepts/persistent/models.md +1 -1
package/content/guides/core-concepts/persistent/pglite.md +218 -0
package/content/guides/core-concepts/persistent/postgres-drivers.md +21 -15
package/content/guides/core-concepts/persistent/search-meilisearch.md +22 -12
package/content/guides/core-concepts/persistent/search-typesense.md +28 -16
package/content/guides/core-concepts/persistent/sqlite.md +296 -0
package/content/guides/core-concepts/persistent/transactions.md +12 -11
package/content/guides/core-concepts/secrets-vault.md +177 -0
package/content/guides/core-concepts/services.md +1 -1
package/content/guides/get-started/5-minute-quickstart.md +59 -206
package/content/guides/get-started/philosophy.md +135 -670
package/content/guides/get-started/setup.md +53 -74
package/content/guides/migrations/redis-helpers-migration.md +5 -4
package/content/guides/migrations/scoped-rbac-migration.md +5 -5
package/content/guides/migrations/unified-connectors-migration.md +8 -7
package/content/guides/tutorials/ecommerce-api.md +3 -8
package/content/guides/tutorials/realtime-chat.md +1 -1
package/content/references/base/application.md +64 -22
package/content/references/base/components.md +3 -3
package/content/references/base/connectors.md +79 -136
package/content/references/base/controllers.md +12 -12
package/content/references/base/datasources-reference.md +600 -0
package/content/references/base/datasources.md +84 -444
package/content/references/base/dependency-injection.md +25 -46
package/content/references/base/filter-system/application-usage.md +95 -123
package/content/references/base/filter-system/array-operators.md +33 -43
package/content/references/base/filter-system/comparison-operators.md +55 -63
package/content/references/base/filter-system/default-filter.md +144 -350
package/content/references/base/filter-system/fields-order-pagination.md +116 -148
package/content/references/base/filter-system/index.md +114 -253
package/content/references/base/filter-system/json-filtering.md +52 -181
package/content/references/base/filter-system/list-operators.md +28 -44
package/content/references/base/filter-system/logical-operators.md +69 -114
package/content/references/base/filter-system/null-operators.md +41 -98
package/content/references/base/filter-system/pattern-matching.md +48 -51
package/content/references/base/filter-system/quick-reference.md +93 -196
package/content/references/base/filter-system/range-operators.md +22 -38
package/content/references/base/filter-system/tips.md +70 -133
package/content/references/base/filter-system/use-cases.md +173 -232
package/content/references/base/grpc-controllers.md +53 -17
package/content/references/base/index.md +5 -3
package/content/references/base/middlewares.md +43 -28
package/content/references/base/models-reference.md +886 -0
package/content/references/base/models.md +81 -1452
package/content/references/base/providers.md +8 -8
package/content/references/base/repositories/advanced.md +281 -419
package/content/references/base/repositories/index.md +84 -644
package/content/references/base/repositories/mixins.md +25 -21
package/content/references/base/repositories/relations.md +194 -375
package/content/references/base/repositories/soft-deletable.md +67 -55
package/content/references/base/secrets.md +267 -0
package/content/references/base/services.md +8 -6
package/content/references/configuration/environment-variables.md +73 -21
package/content/references/configuration/index.md +51 -31
package/content/references/index.md +1 -1
package/content/references/quick-reference.md +3 -16
package/content/references/utilities/crypto.md +35 -76
package/content/references/utilities/date.md +33 -73
package/content/references/utilities/duration.md +85 -0
package/content/references/utilities/index.md +6 -2
package/content/references/utilities/jsx-reference.md +298 -0
package/content/references/utilities/jsx.md +82 -525
package/content/references/utilities/module.md +81 -61
package/content/references/utilities/parse.md +34 -64
package/content/references/utilities/performance.md +33 -58
package/content/references/utilities/promise.md +28 -62
package/content/references/utilities/request.md +58 -218
package/content/references/utilities/retry.md +139 -0
package/content/references/utilities/schema.md +43 -137
package/content/references/utilities/statuses-reference.md +361 -0
package/content/references/utilities/statuses.md +63 -667
package/dist/mcp-server/index.js +0 -0
package/dist/mcp-server/tools/github/list-project-files.tool.d.ts +1 -1
package/dist/mcp-server/tools/github/list-project-files.tool.d.ts.map +1 -1
package/dist/mcp-server/tools/github/list-project-files.tool.js +3 -3
package/dist/mcp-server/tools/github/search-code.tool.js +1 -1
package/dist/mcp-server/tools/github/verify-dependencies.tool.js +1 -1
package/dist/mcp-server/tools/github/view-source-file.tool.js +1 -1
package/package.json +24 -23

package/content/references/utilities/jsx.md CHANGED Viewed

@@ -1,574 +1,131 @@
 ---
-title: JSX/HTML Utilities Reference
-description: Utilities for HTML and JSX responses in OpenAPI routes
+title: JSX/HTML Utility
+description: Render server-side HTML pages with Hono JSX and document them for OpenAPI
 difficulty: beginner
-lastUpdated: 2026-01-03
 ---
 # JSX/HTML Utility
-The JSX utility provides helper functions for defining HTML/JSX response schemas in OpenAPI routes. These utilities are companions to `jsonContent` and `jsonResponse` but for HTML content type.
+IGNIS renders HTML pages server-side with Hono's built-in JSX support, and documents those routes for OpenAPI with `htmlContent()` / `htmlResponse()`.
-**File:** `packages/core/src/utilities/jsx.utility.ts`
+## In one example
-## Quick Reference
+The smallest real JSX route: a controller that renders a component through `defineJSXRoute`.
-| Function | Purpose | Returns |
-|----------|---------|---------|
-| `htmlContent()` | Create HTML content configuration | OpenAPI content object |
-| `htmlResponse()` | Create HTML response with error handling | OpenAPI response object |
-## When to Use
-Use these utilities when creating routes that:
-- Render HTML pages using Hono JSX
-- Return server-side rendered content
-- Serve HTML documentation or views
-- Generate HTML emails or reports
-## htmlContent()
-Creates a standard OpenAPI content object for `text/html` responses.
-### Signature
-```typescript
-function htmlContent(opts: {
-  description: string;
-  required?: boolean;
-}): {
-  description: string;
-  content: {
-    'text/html': {
-      schema: ZodString;
-    };
-  };
-  required: boolean;
-}
-```
-### Parameters
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `description` | `string` | Yes | - | Description of the HTML content |
-| `required` | `boolean` | No | `false` | Whether the content is required |
-### Returns
-Returns an OpenAPI content configuration object with:
-- `description`: The provided description
-- `content`: Content type configuration for `text/html`
-- `required`: Whether the content is required
-### Example
-```typescript
-import { htmlContent } from '@venizia/ignis';
-const pageContent = htmlContent({
-  description: 'HTML page content',
-  required: true,
-});
-// Result:
-// {
-//   description: 'HTML page content',
-//   content: {
-//     'text/html': {
-//       schema: z.string().openapi({
-//         description: 'HTML content',
-//         example: '<!DOCTYPE html><html>...</html>',
-//       }),
-//     },
-//   },
-//   required: true,
-// }
-```
-## htmlResponse()
-Creates a standard OpenAPI response object for HTML endpoints, including a success (200 OK) HTML response and a JSON error response for `4xx | 5xx` status codes using the `ErrorSchema`.
-### Signature
-```typescript
-function htmlResponse(opts: {
-  description: string;
-  required?: boolean;
-}): {
-  200: typeof htmlContent;
-  '4xx | 5xx': {
-    description: 'Error Response';
-    content: {
-      'application/json': {
-        schema: ErrorSchema;
-      };
-    };
-  };
-}
-```
-### Parameters
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `description` | `string` | Yes | - | Description of the successful HTML response |
-| `required` | `boolean` | No | `false` | Whether the content is required |
-### Returns
-Returns an OpenAPI responses object with:
-- `200`: Success response with HTML content (via `htmlContent()`)
-- `4xx | 5xx`: Error responses with JSON error schema
-### Example
-```typescript
-import { htmlResponse } from '@venizia/ignis';
-this.defineRoute({
-  configs: {
-    path: '/dashboard',
-    method: 'get',
-    responses: htmlResponse({
-      description: 'Dashboard HTML page',
-    }),
-  },
-  handler: async (context) => {
-    return context.html(
-      <html>
-        <head>
-          <title>Dashboard</title>
-        </head>
-        <body>
-          <h1>Welcome to Dashboard</h1>
-        </body>
-      </html>
-    );
-  },
-});
-```
-## Usage Examples
-### Basic HTML Route
-```typescript
-import { BaseRestController, get, htmlResponse } from '@venizia/ignis';
-export class PageController extends BaseRestController {
-  @get({
-    configs: {
-      path: '/home',
-      responses: htmlResponse({
-        description: 'Home page HTML',
-      }),
-    },
-  })
-  async getHomePage() {
-    return this.context.html(
-      <html>
-        <head>
-          <title>Home</title>
-        </head>
-        <body>
-          <h1>Welcome Home</h1>
-        </body>
-      </html>
-    );
-  }
-}
-```
-### HTML Email Preview
-```typescript
-import { BaseRestController, get, htmlResponse, TRouteContext } from '@venizia/ignis';
-import { z } from '@hono/zod-openapi';
-import { HTTP } from '@venizia/ignis-helpers';
-const EmailRoutes = {
-  PREVIEW: {
-    method: HTTP.Methods.GET,
-    path: '/preview/:templateId',
-    request: {
-      params: z.object({ templateId: z.string() }),
-    },
-    responses: htmlResponse({
-      description: 'Email template preview',
-    }),
-  },
-} as const;
-export class EmailController extends BaseRestController {
-  @get({ configs: EmailRoutes.PREVIEW })
-  async previewTemplate(c: TRouteContext) {
-    const { templateId } = c.req.valid<{ templateId: string }>('param');
-    const template = await this.emailService.getTemplate(templateId);
-    return c.html(
-      <html>
-        <head>
-          <title>Email Preview: {template.subject}</title>
-        </head>
-        <body>
-          <div dangerouslySetInnerHTML={{ __html: template.html }} />
-        </body>
-      </html>
-    );
-  }
-}
-```
-### Documentation Page
-```typescript
-import { BaseRestController, get, htmlResponse, TRouteContext } from '@venizia/ignis';
-import { z } from '@hono/zod-openapi';
+```tsx
+import { BaseRestController, controller, htmlContent, type IControllerOptions } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
-const DocsRoutes = {
-  GET_SECTION: {
-    method: HTTP.Methods.GET,
-    path: '/docs/:section',
-    request: {
-      params: z.object({ section: z.string() }),
-    },
-    responses: htmlResponse({
-      description: 'API documentation page',
-    }),
-  },
-} as const;
-export class DocsController extends BaseRestController {
-  @get({ configs: DocsRoutes.GET_SECTION })
-  async getDocumentation(c: TRouteContext) {
-    const { section } = c.req.valid<{ section: string }>('param');
-    const content = await this.docsService.getSection(section);
-    return c.html(
-      <html>
-        <head>
-          <title>Docs - {content.title}</title>
-          <link rel="stylesheet" href="/styles/docs.css" />
-        </head>
-        <body>
-          <nav>
-            <a href="/docs/getting-started">Getting Started</a>
-            <a href="/docs/api">API Reference</a>
-          </nav>
-          <main>
-            <h1>{content.title}</h1>
-            <div dangerouslySetInnerHTML={{ __html: content.html }} />
-          </main>
-        </body>
-      </html>
-    );
+@controller({ path: '/' })
+export class ViewController extends BaseRestController {
+  constructor(opts: IControllerOptions) {
+    super({ ...opts, scope: ViewController.name, path: '/' });
   }
-}
-```
-### Admin Dashboard
-```typescript
-import { BaseRestController, get, htmlResponse } from '@venizia/ignis';
-export class AdminController extends BaseRestController {
-  @get({
-    configs: {
-      path: '/admin',
-      middleware: [authenticate({ role: 'admin' })],
-      responses: htmlResponse({
-        description: 'Admin dashboard',
-      }),
-    },
-  })
-  async getDashboard() {
-    const stats = await this.statsService.getAdminStats();
-    return this.context.html(
-      <html>
-        <head>
-          <title>Admin Dashboard</title>
-          <script src="/js/dashboard.js" defer />
-        </head>
-        <body>
-          <div class="dashboard">
-            <h1>Admin Dashboard</h1>
-            <div class="stats">
-              <div class="stat-card">
-                <h3>Total Users</h3>
-                <p>{stats.totalUsers}</p>
-              </div>
-              <div class="stat-card">
-                <h3>Active Sessions</h3>
-                <p>{stats.activeSessions}</p>
-              </div>
-            </div>
-          </div>
-        </body>
-      </html>
-    );
+  override binding() {
+    this.defineJSXRoute({
+      configs: {
+        path: '/',
+        method: 'get',
+        responses: {
+          [HTTP.ResultCodes.RS_2.Ok]: htmlContent({ description: 'Home page HTML' }),
+        },
+      },
+      handler: c => c.html(<h1>Welcome to IGNIS</h1>),
+    });
   }
 }
 ```
+No separate JSX renderer is registered - the handler builds a JSX tree and hands it to Hono's own `c.html()`.
-## Comparison with JSON Utilities
+## How it works
-### htmlContent vs jsonContent
+- **Hono JSX renders to HTML.** A handler returns `c.html(<Component />)`; Hono's built-in JSX runtime turns the tree into an HTML string. IGNIS adds nothing on top of that renderer.
+- **`defineJSXRoute` is `defineRoute` with an HTML default.** It builds route configs through `getJSXRouteConfigs` instead of `getRouteConfigs`, which merges a default `htmlResponse({ description: 'HTML page' })` under whatever `responses` you declare - your own `200` entry overrides the default description.
+- **`htmlContent()` / `htmlResponse()` document `text/html`.** They mirror `jsonContent()` / `jsonResponse()` (see [Schema Utility](./schema.md)) but for HTML: `htmlContent()` builds one OpenAPI content object, `htmlResponse()` wraps it into a full `200` success response plus a JSON `4xx | 5xx` error response.
+- **The tsconfig switch is required.** Compiling `.tsx` files with Hono's JSX needs `"jsx": "react-jsx"` and `"jsxImportSource": "hono/jsx"` in `tsconfig.json`.
-| Aspect | `htmlContent()` | `jsonContent()` |
-|--------|----------------|-----------------|
-| **Content-Type** | `text/html` | `application/json` |
-| **Schema** | `z.string()` | Custom Zod schema |
-| **Use Case** | HTML pages, JSX rendering | API responses, data |
-| **Example** | HTML document string | JSON object |
+## Common tasks
-### htmlResponse vs jsonResponse
+### Build a reusable layout
-| Aspect | `htmlResponse()` | `jsonResponse()` |
-|--------|------------------|------------------|
-| **Success Type** | `text/html` (200) | `application/json` (200) |
-| **Error Type** | `application/json` (4xx/5xx) | `application/json` (4xx/5xx) |
-| **Use Case** | Web pages | REST APIs |
+Compose pages from a shared layout using `FC` and `PropsWithChildren`, re-exported from `@venizia/ignis-helpers` (sourced from `hono/jsx`).
+```tsx
+import type { FC, PropsWithChildren } from '@venizia/ignis-helpers';
-## Best Practices
-### 1. Use for Server-Side Rendering
-```typescript
-// Good: Use htmlResponse for SSR routes
-const ProfileConfig = {
-  method: HTTP.Methods.GET,
-  path: '/profile/:userId',
-  request: { params: z.object({ userId: z.string() }) },
-  responses: htmlResponse({ description: 'User profile page' }),
-} as const;
-@get({ configs: ProfileConfig })
-async getUserProfile(c: TRouteContext) {
-  const { userId } = c.req.valid<{ userId: string }>('param');
-  const user = await this.userService.getUser(userId);
-  return c.html(<UserProfile user={user} />);
-}
-// Bad: Don't use htmlResponse for API endpoints - use jsonResponse instead
+export const MainLayout: FC<PropsWithChildren<{ title: string }>> = ({ title, children }) => (
+  <html>
+    <head>
+      <title>{title}</title>
+    </head>
+    <body>{children}</body>
+  </html>
+);
 ```
-### 2. Combine with Authentication
-```typescript
-const SettingsConfig = {
-  method: HTTP.Methods.GET,
-  path: '/admin/settings',
-  authenticate: { strategies: ['jwt'] },
-  responses: htmlResponse({ description: 'Settings page' }),
-} as const;
-@get({ configs: SettingsConfig })
-async getSettings(c: TRouteContext) {
-  return c.html(<SettingsPage />);
-}
-```
-### 3. Error Handling
-HTML routes automatically return JSON errors for 4xx/5xx:
-```typescript
-const ArticleConfig = {
-  method: HTTP.Methods.GET,
-  path: '/article/:id',
-  request: { params: z.object({ id: z.string() }) },
-  responses: htmlResponse({ description: 'Article page' }),
-} as const;
-@get({ configs: ArticleConfig })
-async getArticle(c: TRouteContext) {
-  const { id } = c.req.valid<{ id: string }>('param');
-  const article = await this.articleService.findById(id);
+### Pass props into a page component
-  if (!article) {
-    // Returns JSON error: { message: 'Not found', statusCode: 404 }
-    throw new NotFoundError('Article not found');
-  }
+Page components take a typed props object like any other Hono JSX component.
-  return c.html(<ArticlePage article={article} />);
+```tsx
+interface HomePageProps {
+  timestamp?: string;
 }
-```
-### 4. SEO-Friendly Metadata
-```typescript
-const BlogConfig = {
-  method: HTTP.Methods.GET,
-  path: '/blog/:slug',
-  request: { params: z.object({ slug: z.string() }) },
-  responses: htmlResponse({ description: 'Blog post page' }),
-} as const;
-@get({ configs: BlogConfig })
-async getBlogPost(c: TRouteContext) {
-  const { slug } = c.req.valid<{ slug: string }>('param');
-  const post = await this.blogService.getBySlug(slug);
-  return c.html(
-    <html>
-      <head>
-        <title>{post.title} | My Blog</title>
-        <meta name="description" content={post.excerpt} />
-        <meta property="og:title" content={post.title} />
-        <meta property="og:description" content={post.excerpt} />
-        <meta property="og:image" content={post.coverImage} />
-      </head>
-      <body>
-        <article>
-          <h1>{post.title}</h1>
-          <div dangerouslySetInnerHTML={{ __html: post.content }} />
-        </article>
-      </body>
-    </html>
-  );
-}
+export const HomePage: FC<HomePageProps> = ({ timestamp }) => (
+  <MainLayout title="Home">
+    <h1>Welcome</h1>
+    {timestamp && <p>Rendered at {timestamp}</p>}
+  </MainLayout>
+);
 ```
+### Render trusted raw HTML
-## Integration with Hono JSX
-IGNIS uses Hono's built-in JSX support. Make sure to configure your `tsconfig.json`:
+Use `dangerouslySetInnerHTML` for content that is already HTML, such as a stored email or blog template - never for unsanitized user input.
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "jsxImportSource": "hono/jsx"
-  }
-}
+```tsx
+<div dangerouslySetInnerHTML={{ __html: template.html }} />
 ```
-### JSX Components
-```typescript
-// components/Layout.tsx
-export const Layout = (props: { title: string; children: any }) => {
-  return (
-    <html>
-      <head>
-        <title>{props.title}</title>
-        <link rel="stylesheet" href="/styles/main.css" />
-      </head>
-      <body>
-        <header>
-          <nav>
-            <a href="/">Home</a>
-            <a href="/about">About</a>
-          </nav>
-        </header>
-        <main>{props.children}</main>
-        <footer>
-          <p>&copy; 2026 My App</p>
-        </footer>
-      </body>
-    </html>
-  );
-};
-// controller.ts
-import { Layout } from './components/Layout';
-@get({
-  configs: {
-    path: '/',
-    responses: htmlResponse({ description: 'Home page' }),
-  },
-})
-async getHome() {
-  return this.context.html(
-    <Layout title="Home">
-      <h1>Welcome to My App</h1>
-      <p>This is the home page.</p>
-    </Layout>
-  );
-}
-```
-## Common Pitfalls
-### Pitfall 1: Missing HTML Wrapper
+### Give the response a custom description
-```typescript
-// Bad: Incomplete HTML
-@get({
-  configs: {
-    path: '/page',
-    responses: htmlResponse({ description: 'Page' }),
-  },
-})
-async getPage() {
-  return this.context.html(<div>Hello</div>); // Missing <html>, <head>, <body>
-}
+Pass your own `200` entry in `responses` - it overrides the `defineJSXRoute` default description.
-// Good: Complete HTML document
-@get({
-  configs: {
-    path: '/page',
-    responses: htmlResponse({ description: 'Page' }),
-  },
-})
-async getPage() {
-  return this.context.html(
-    <html>
-      <head><title>Page</title></head>
-      <body><div>Hello</div></body>
-    </html>
-  );
-}
+```tsx
+responses: {
+  [HTTP.ResultCodes.RS_2.Ok]: htmlContent({ description: 'Dashboard HTML page' }),
+},
 ```
-### Pitfall 2: Using htmlResponse for APIs
+### Guard a page with authentication
-```typescript
-// Bad: HTML response for API
-@get({
-  configs: {
-    path: '/api/users',
-    responses: htmlResponse({ description: 'Users' }),
-  },
-})
-async getUsers() {
-  return { users: [...] }; // Should return HTML or use jsonResponse
-}
+JSX routes accept the same `authenticate` config as JSON routes.
-// Good: Use jsonResponse for APIs
-@get({
+```tsx
+this.defineJSXRoute({
   configs: {
-    path: '/api/users',
-    responses: jsonResponse({
-      description: 'Users list',
-      schema: z.object({ users: z.array(UserSchema) }),
-    }),
+    path: '/admin',
+    method: 'get',
+    authenticate: { strategies: ['jwt'] },
+    responses: {
+      [HTTP.ResultCodes.RS_2.Ok]: htmlContent({ description: 'Admin dashboard' }),
+    },
   },
-})
-async getUsers() {
-  return { users: await this.userService.findAll() };
-}
+  handler: c => c.html(<AdminDashboard />),
+});
 ```
+## See also
-## See Also
+- [Full reference](/references/utilities/jsx-reference) - every function, `defineJSXRoute` behavior, and component patterns
+- [Schema Utility](./schema.md) - the JSON-side helpers (`jsonContent`, `jsonResponse`) this pairs with
+- [Controllers](../base/controllers.md) - `defineRoute`/`bindRoute`, `authenticate`/`authorize` config
+- **External:** [Hono JSX Documentation](https://hono.dev/docs/guides/jsx)
-- **Related References:**
-  - [Schema Utility](./schema.md) - JSON content and response helpers
-  - [Controllers](../base/controllers.md) - Defining routes and handlers
-  - [OpenAPI Component](/extensions/components/api-reference) - API documentation
+**Files:**
-- **External Resources:**
-  - [Hono JSX Documentation](https://hono.dev/guides/jsx)
-  - [OpenAPI Specification](https://swagger.io/specification/)
-  - [React JSX (for reference)](https://react.dev/learn/writing-markup-with-jsx)
+- [`packages/core-server/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/utilities/jsx.utility.ts) - `htmlContent`, `htmlResponse`
+- [`packages/core-server/src/base/controllers/rest/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/rest/base.ts) - `defineJSXRoute`