{"id":15419,"library":"build-plugin-ice-router","title":"icejs Router Plugin","description":"build-plugin-ice-router provides comprehensive routing capabilities for the icejs framework. At its current stable version 2.1.3, it supports both convention-based routing, automatically generating routes from the `src/pages` directory structure, and configuration-based routing, allowing developers to define routes explicitly in `src/routes.[ts|js]`. Key differentiators include built-in support for nested layouts (using `_layout.tsx`), dynamic route parameters (e.g., `/$uid.tsx` for `/app/:uid`), and optional dynamic parameters (`/$uid$.tsx` for `/app/:uid?`). It also offers dedicated features for global layouts via `src/layouts/index.tsx` and 404 error pages via `src/pages/404.tsx`. This plugin is primarily associated with the icejs v2 ecosystem. The broader Alibaba/ICE framework has evolved to `@ice/app` in v3, which introduces a potentially different plugin system and core architecture. Users should be aware of this version distinction when integrating, as `build-plugin-ice-router` targets icejs v2.","status":"maintenance","version":"2.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/alibaba/ice/tree/master/packages/plugin-router","tags":["javascript"],"install":[{"cmd":"npm install build-plugin-ice-router","lang":"bash","label":"npm"},{"cmd":"yarn add build-plugin-ice-router","lang":"bash","label":"yarn"},{"cmd":"pnpm add build-plugin-ice-router","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a build plugin designed to work with the icejs framework (v2). It expects `ice` to be a peer dependency of the application it's building.","package":"ice","optional":false}],"imports":[{"note":"`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`.","wrong":"import { runApp } from '@ice/app';","symbol":"runApp","correct":"import { runApp } from 'ice';"},{"note":"When using configuration-based routing, the `src/routes.[ts|js]` file should export the array of route objects as its default export.","symbol":"routes","correct":"import routes from './routes';"},{"note":"This type definition is available from the `ice` package to strongly type the router configuration object passed to `runApp`.","symbol":"IAppRouterConfig","correct":"import type { IAppRouterConfig } from 'ice';"}],"quickstart":{"code":"/* src/app.ts */\nimport { runApp } from 'ice';\nimport type { IAppRouterConfig } from 'ice';\n\nconst appConfig: { router?: IAppRouterConfig } = {\n router: {\n type: 'browser',\n basename: '/',\n modifyRoutes: (routes) => {\n console.log('Routes generated:', routes);\n return routes;\n }\n }\n};\n\nrunApp(appConfig);\n\n/* src/pages/index.tsx */\nimport React from 'react';\nimport { Link } from 'ice'; // Example of a router-provided component\n\nconst Home = () => {\n return (\n
\n
Welcome to icejs Home!
\n
This is a convention-based route generated by build-plugin-ice-router.
\n Go to About\n
\n );\n};\n\nexport default Home;\n\n/* src/pages/About/index.tsx */\nimport React from 'react';\n\nconst About = () => {\n return (\n
\n
About Page
\n
Another convention-based route from `src/pages/About/index.tsx`.
\n
\n );\n};\n\nexport default About;\n\n/* build.json */\n// Optional: Configure build-time router options, e.g., to ignore specific paths.\n// {\n// \"router\": {\n// \"ignorePaths\": [\"stores\", \"components\"]\n// }\n// }","lang":"typescript","description":"Sets up a minimal icejs application demonstrating convention-based routing. It defines a home page and an 'about' page, configured through `src/app.ts`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.x"},{"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]`.","message":"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.","severity":"gotcha","affected_versions":">=2.x"},{"fix":"To enforce case sensitivity, add `\"router\": { \"caseSensitive\": true }` to your `build.json`. Ensure consistent casing in your file/directory names and route links.","message":"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`.","severity":"gotcha","affected_versions":">=2.x"},{"fix":"Carefully review the dynamic route naming conventions in the documentation. Test dynamic route paths thoroughly to ensure they resolve correctly.","message":"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.","severity":"gotcha","affected_versions":">=2.x"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Not Found: [route path]"},{"fix":"Ensure `src/app.ts` includes an `appConfig` object with a properly structured `router` property, for example: `{ router: { type: 'browser', basename: '/' } }`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'router') when calling runApp"},{"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`).","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.","error":"Error: Cannot find module 'ice'"}],"ecosystem":"npm"}