icejs Router Plugin

Common errors

• Error: Not Found: [route path]

  cause The requested route path does not match any defined convention-based or configuration-based route, or the 404 page is not correctly placed/configured.
  fix Verify that your page components are correctly placed in `src/pages` for convention-based routing, or that your `src/routes.ts` file accurately defines the path. Ensure `src/pages/404.tsx` (or `src/pages/404/index.tsx`) exists for a custom 404 page.

• TypeError: Cannot read properties of undefined (reading 'router') when calling runApp

  cause The router configuration object (`router` property) passed to `runApp` in `src/app.ts` is either missing or malformed, preventing the router from initializing correctly.
  fix Ensure `src/app.ts` includes an `appConfig` object with a properly structured `router` property, for example: `{ router: { type: 'browser', basename: '/' } }`.

• Error: Cannot find module 'ice'

  cause The `ice` core framework package is not installed, or there's an issue with module resolution in your project, often due to an incorrect `package.json` setup or `node_modules` state.
  fix Install the `ice` package via `npm install ice` or `yarn add ice`. If already installed, try clearing your package manager cache and reinstalling dependencies (`npm cache clean --force && rm -rf node_modules && npm install`).

Warnings

• breaking This plugin (`build-plugin-ice-router` v2.x) is strictly designed for icejs v2 applications. Migrating to `@ice/app` (v3.x) will require replacing this plugin with `@ice/plugin-router` or leveraging the built-in routing solution provided by the new `@ice/app` framework. Direct compatibility is not guaranteed.
  Fix: For `@ice/app` v3 projects, refer to the official `@ice/app` documentation for its routing solution, typically involving `@ice/plugin-router`. Remove `build-plugin-ice-router` from your `package.json` and build configuration.
• gotcha When both convention-based routing (pages in `src/pages`) and configuration-based routing (an explicit `src/routes.[ts|js]` file) are detected, the configuration file takes full precedence. Convention-based routes will be ignored.
  Fix: If you intend to use convention-based routing, ensure no `src/routes.[ts|js]` file exists. If using configuration-based, ensure all desired routes are explicitly defined in `src/routes.[ts|js]`.
• gotcha By default, route paths generated from the file system are case-insensitive. If strict case matching is required, you must enable the `caseSensitive` option in your `build.json`.
  Fix: To enforce case sensitivity, add `"router": { "caseSensitive": true }` to your `build.json`. Ensure consistent casing in your file/directory names and route links.
• gotcha Dynamic routes use specific naming conventions: `src/pages/$param.tsx` for a mandatory parameter (`/:param`), and `src/pages/$param$.tsx` for an optional parameter (`/:param?`). Incorrect use of `$` will lead to routes not being generated or matched as expected.
  Fix: Carefully review the dynamic route naming conventions in the documentation. Test dynamic route paths thoroughly to ensure they resolve correctly.

Install

• npm install build-plugin-ice-router npm
• yarn add build-plugin-ice-router yarn
• pnpm add build-plugin-ice-router pnpm

Imports

• runApp
  wrong:

  import { runApp } from '@ice/app';

  correct:

  import { runApp } from 'ice';

  `runApp` is the entry point for icejs v2 applications using this plugin. For applications built with `@ice/app` (v3+), the `runApp` symbol would typically be imported from `@ice/app`.
• routes

  import routes from './routes';

  When using configuration-based routing, the `src/routes.[ts|js]` file should export the array of route objects as its default export.
• IAppRouterConfig

  import type { IAppRouterConfig } from 'ice';

  This type definition is available from the `ice` package to strongly type the router configuration object passed to `runApp`.

Quickstart

Sets up a minimal icejs application demonstrating convention-based routing. It defines a home page and an 'about' page, configured through `src/app.ts`.

/* src/app.ts */
import { runApp } from 'ice';
import type { IAppRouterConfig } from 'ice';

const appConfig: { router?: IAppRouterConfig } = {
  router: {
    type: 'browser',
    basename: '/',
    modifyRoutes: (routes) => {
      console.log('Routes generated:', routes);
      return routes;
    }
  }
};

runApp(appConfig);

/* src/pages/index.tsx */
import React from 'react';
import { Link } from 'ice'; // Example of a router-provided component

const Home = () => {
  return (
    <div>
      <h1>Welcome to icejs Home!</h1>
      <p>This is a convention-based route generated by build-plugin-ice-router.</p>
      <Link to="/about">Go to About</Link>
    </div>
  );
};

export default Home;

/* src/pages/About/index.tsx */
import React from 'react';

const About = () => {
  return (
    <div>
      <h2>About Page</h2>
      <p>Another convention-based route from `src/pages/About/index.tsx`.</p>
    </div>
  );
};

export default About;

/* build.json */
// Optional: Configure build-time router options, e.g., to ignore specific paths.
// {
//   "router": {
//     "ignorePaths": ["stores", "components"]
//   }
// }