Registry / web-framework / build-plugin-ice-router

build-plugin-ice-router

library2.1.3jsnpmunverified

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.

web-framework

npm install build-plugin-ice-router

github ↗package ↗

INSTALL

IMPORT

SIG · BUILD-PLUGIN-ICE-R

build-plugin-ice-router

web-frameworkjavascriptv2.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

runApp

✓ import { runApp } from 'ice';

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

`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`.

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"] // } // }

Debug

Known issues

breakingThis 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.

affects: >=2.x

gotchaWhen 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]`.

affects: >=2.x

gotchaBy 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.

affects: >=2.x

gotchaDynamic 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.

affects: >=2.x

Errors

Common errors & fixes

Error: Not Found: [route path]

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

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'

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`).

Upgrade

Version history

2.1.3latest on npm

Audit

Dependencies

icerequiredThis 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.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/alibaba/ice ↗

packagehttps://www.npmjs.com/package/build-plugin-ice-router ↗