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-routerVerified import paths — ran on the pinned version, not inferred.
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`.
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.
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`.
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.
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.
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.
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.
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.No dependency data recorded yet.