Registry / web-framework / stx-router

stx-router

JSON →
library0.2.12jsnpmunverified

STX Router is a file-based routing solution specifically designed for the Stacks.js full-stack framework. It facilitates automatic discovery of `.stx` templates, enables nested layouts, offers typed route parameters for enhanced developer experience and compile-time safety, supports middleware for request processing, and provides robust client-side SPA navigation. As of version 0.2.12, the package is in active pre-1.0 development, integrating seamlessly into the Stacks.js ecosystem which leverages TypeScript and Bun for performance and type-safety. The project generally follows a convention-over-configuration philosophy, aiming for rapid application development. Its current release cadence is frequent, indicating ongoing feature development and potential for breaking changes between minor versions as it approaches a stable 1.0 release.

npm install stx-router
INSTALL
IMPORT
SIG · STX-ROUTER
S
stx-router
web-frameworkjavascriptv0.2.12
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createRouter
import { createRouter } from '@stacksjs/router'
const { createRouter } = require('@stacksjs/router')
STX Router is primarily designed for ESM environments and TypeScript, aligning with the Stacks.js framework's architecture.
defineMiddleware
import { defineMiddleware } from '@stacksjs/router'
import defineMiddleware from '@stacksjs/router'
Middleware functions are typically defined using `defineMiddleware` for proper integration with the routing pipeline and type inference.
RouteContext
import type { RouteContext } from '@stacksjs/router'
Importing types like `RouteContext` should always use `import type` to ensure they are stripped during compilation and do not introduce runtime overhead.

This quickstart demonstrates how to initialize `stx-router` with a file-based route directory, apply a simple authentication middleware to protected paths, and shows a basic request handling flow within a simulated Stacks.js server environment. It highlights the use of `createRouter` and `defineMiddleware`.

import { createRouter, defineMiddleware } from '@stacksjs/router'; import { fileURLToPath } from 'node:url'; import { dirname, join } from 'node:path'; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); // Define a simple authentication middleware const authMiddleware = defineMiddleware((req, res, next) => { const isAuthenticated = req.headers.get('authorization') === 'Bearer my-secret-token'; if (isAuthenticated) { console.log('User is authenticated'); next(); } else { console.warn('Authentication failed: Missing or invalid token'); res.status(401).send('Unauthorized'); } }); // Imagine your .stx templates are in a 'views' directory // For a file-based router, you'd typically have files like: // views/index.stx, views/users/[id].stx, views/admin/dashboard.stx const router = createRouter({ routes: join(__dirname, 'views'), // Points to your .stx template directory middleware: { '/admin/*': [authMiddleware], // Apply authMiddleware to all /admin routes }, // You might define custom error handlers or other router options here onNotFound: (req, res) => { res.status(404).send('Custom 404 Not Found Page'); }, }); // Example: How to manually handle a request (in a server context, e.g., Bun.serve) // In a real Stacks.js app, this would be abstracted away by the framework's server. async function handleRequest(request: Request) { const url = new URL(request.url); console.log(`Incoming request: ${request.method} ${url.pathname}`); // Simulate router matching and processing // In a full Stacks.js app, this would trigger .stx template rendering const response = await router.handle(request); // For demonstration, a simple placeholder response if router doesn't explicitly respond if (!response.headers.has('X-Router-Handled')) { if (url.pathname === '/') { return new Response('Welcome to the STX App!', { status: 200 }); } else if (url.pathname.startsWith('/users/')) { const userId = url.pathname.split('/').pop(); return new Response(`User profile for ID: ${userId}`, { status: 200 }); } return new Response('Default response for unmatched routes or handled by custom 404', { status: 404 }); } return response; } // This part would typically be part of your Stacks.js server setup // Bun.serve({ // fetch: handleRequest, // port: 3000, // }); // console.log('STX Router example server running on http://localhost:3000'); // To test manually: // await handleRequest(new Request('http://localhost:3000/')); // await handleRequest(new Request('http://localhost:3000/users/123')); // await handleRequest(new Request('http://localhost:3000/admin/dashboard', { headers: { 'Authorization': 'Bearer my-secret-token' } })); // await handleRequest(new Request('http://localhost:3000/admin/settings')); // Should be unauthorized // await handleRequest(new Request('http://localhost:3000/nonexistent')); // Should trigger custom 404
Debug
Known issues
breakingAs a pre-1.0 release, `stx-router` may introduce breaking changes in minor versions (e.g., 0.2.x to 0.3.x). APIs, configuration options, and internal behaviors are subject to change without strict adherence to semantic versioning until a stable 1.0 release.
fix
Always review the release notes or changelog when upgrading minor versions. Pin exact versions in your `package.json` to prevent unexpected breaking changes in production, and test thoroughly before deploying updates.
affects: >=0.1.0
gotchaFile-based routing relies on specific directory structures and naming conventions for `.stx` templates. Deviating from these conventions will result in routes not being discovered or matched correctly, leading to 404 errors.
fix
Consult the Stacks.js documentation for the exact file-based routing conventions, especially regarding dynamic segments (e.g., `[id].stx`), nested layouts, and index files. Ensure your template directory path is correctly configured in `createRouter`.
affects: >=0.1.0
gotchaMiddleware execution order and application scope can be a common source of bugs. Middleware might not execute for certain routes, or the order of execution might be unexpected, especially with overlapping paths.
fix
Carefully define your middleware paths and ensure they are specified in the correct order in your router configuration. Use logging within your middleware to verify their execution flow for specific requests. Broad wildcard (`*`) paths should be used with caution.
affects: >=0.1.0
gotchaTyped route parameters, while beneficial, require careful definition in your route files (or inferred types). Incorrectly accessing or assuming the type of a route parameter (e.g., treating a string ID as a number without parsing) can lead to runtime `TypeError`s.
fix
Always validate and parse route parameters explicitly in your route handlers or middleware, especially when converting between string path segments and numerical/boolean types. Leverage TypeScript's type inference and type guards to handle parameter types safely.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Route not found for path '/your/path'
The requested URL path does not match any defined file-based route in your `.stx` template directory, or the router configuration is incorrect.
fix
Verify that a corresponding `.stx` file exists for the requested path (e.g., `views/your/path.stx` or `views/your/[param].stx`). Check the `routes` configuration in `createRouter` to ensure it points to the correct base directory. Also, confirm no typos in the URL or route definition.
TypeError: Cannot read properties of undefined (reading 'params')
Attempting to access `req.params` or `ctx.params` when no route parameters are present for the matched route, or when the request context (`ctx`/`req`) is not correctly populated by the router.
fix
Ensure that the route being handled actually defines dynamic parameters (e.g., `/users/:id`). Before accessing `params`, consider optional chaining (`req.params?.id`) or a null/undefined check to handle cases where parameters might not exist gracefully.
SyntaxError: Named export 'defineMiddleware' not found in module '@stacksjs/router'
This usually indicates a mismatch between CommonJS `require()` syntax and an ESM module, or an incorrect named import from a module that uses default exports (or vice-versa).
fix
Ensure you are using `import { defineMiddleware } from '@stacksjs/router'` for named exports. If the module primarily offers a default export, you would use `import Router from '@stacksjs/router'` (though `stx-router` uses named exports). Also, verify your project's `tsconfig.json` and `package.json` (`"type": "module"`) are correctly configured for ESM.
Upgrade
Version history
0.2.12latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
1
Resources