# alibaba/ice: the React framework that ships SSR, SSG and miniapp builds from one config

> ice.js is Alibaba's MIT-licensed React application framework, now on the 3.x line. It bundles routing, data loading, SSR and SSG behind a plugin system, and its last push to master was on 2026-04-02.

**alibaba/ice** — 🚀 ice.js: The Progressive App Framework Based On React（基于 React 的渐进式应用框架）

- Repository: https://github.com/alibaba/ice
- Website: https://ice.work
- Stars: 18,613 · Forks: 2,104
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/alibaba-ice

## What problem ice.js solves, and for whom

Most React projects start as a bundler configuration problem. You pick Vite or webpack, add a router, decide how data loads before render, then discover that server-side rendering needs a separate entry point and a different build output. ice.js is an attempt to remove that assembly step. The README describes it as "A universal framework based on React.js" and lists zero-config support for ES6+, TypeScript, Less, Sass and CSS Modules as the first feature. The target reader is a team that wants a working React app with routing and rendering modes decided by configuration rather than by glue code.

The word the README uses for this is "Progressive", which in practice means you are not locked into one rendering mode at the start. A project can begin as a client-rendered SPA and later switch to pre-rendering at build time or at request time. That is the actual selling point: the same project structure survives a change in how the page is delivered. Teams that already have a settled Vite or Next.js setup gain little from that flexibility, because they have already made the decision ice.js keeps open.

## How the plugin system and file-system routing fit together

The repository is a pnpm monorepo. The top level holds packages/, examples/, website/, tests/ and scripts/, with pnpm-workspace.yaml and pnpm-lock.yaml at the root and a build script that runs pnpm -r --filter=./packages/* run build. Everything the framework does at build time lives under packages/. That layout is the clearest statement of the architecture: the framework itself is a set of packages, and the README's fourth feature, "Plugin system", is how those packages are composed into your application.

The examples/ directory is the second half of the picture. It contains a directory per capability rather than per feature bullet: csr-project, with-data-loader, disable-data-loader, routes-config, routes-generate, single-route, hash-router, memory-router, with-basename, icestark-child and icestark-layout, plus multi-target and miniapp-project. Reading that list tells you more about the framework than the feature bullets do. Routing can be configured explicitly or generated from the file system, data loading can be turned off per project, the router can run in hash or memory mode, and the same source can be built for web, miniapp and Weex targets. icestark-child and icestark-layout are the microfrontend entries, which is where the framework's Alibaba lineage shows most clearly.

One consequence is worth stating plainly. Because the plugin system owns the build, the build is not something you patch around. If a plugin's defaults do not match your deployment, you write a plugin or you leave. The examples/with-first-chunk-cache-ssr directory suggests this is a framework where caching behaviour at the SSR boundary is treated as a first-class concern, not an afterthought bolted on with a custom server.

## Installing ice.js and getting a first app running

The README recommends create-ice and gives a single command. It scaffolds a project from a named template, and the lite scaffold is the one the README uses in its example. The npm init form requires npm 6 or later, which the README states explicitly.

```bash
npm init ice ice-app --template @ice/lite-scaffold
```

After scaffolding, the README's next three commands install dependencies and start the development server. The README states the server runs on http://localhost:3000.

```bash
cd ice-app
npm install
npm run start # running on http://localhost:3000.
```

If you see a compile error instead of a page, the usual cause is a Node version mismatch rather than anything in the generated code, since the root package.json pins @types/node to ^17.

## Choosing a template before you write code

The scaffold command is the decision point, and the README documents only the lite template by name. The repository's examples/ directory is the practical index of what else exists: with-antd, with-antd5, with-antd-mobile, with-auth, with-dynamic, with-fallback-entry, app-config, basic-project, cavans-project, rax-project and rax-inline-style. If your application needs an authentication boundary, with-auth is closer to your starting shape than lite-scaffold, and switching later means moving routing and data-loading conventions rather than editing a config file.

This is the part of ice.js that documentation alone will not carry you through. The README lists five features and a quick start; it does not enumerate templates, and it does not explain the difference between routes-config and routes-generate. You will be reading examples/ either way, so pick the example that matches your target before you pick the template.

## Where ice.js is the wrong choice

The release history is the first constraint. The newest release listed is v3.6.2 from 2025-06-30, with @ice/app@3.6.1 a week earlier and @ice/app@3.6.0 on 2025-04-08. The last push to master was on 2026-04-02. That is a repository that is still receiving commits, but the gap between the most recent tagged release and the most recent push is roughly nine months, so anyone depending on a published package is running code that predates the current master branch. If your organisation requires a release cadence you can plan against, that gap is the thing to measure, not the commit history.

The second constraint is the plugin system itself. A framework that owns the build also owns your escape hatches: swapping the bundler, or running a custom server that does not fit the documented SSR path, means working against the framework rather than with it. The README does not document a supported path for ejecting, and it does not describe a rollback procedure for a bad plugin upgrade. Teams that need to own every layer of their build should use a bundler directly and assemble the pieces themselves.

The third is the multi-end claim. The README lists web, miniapp and Weex support, and examples/miniapp-project and examples/rax-project exist, but nothing in the README describes the maturity of the miniapp or Weex targets relative to the web target. Treat the web target as the documented one and verify the others against the examples before planning around them.

## How ice.js compares with assembling Vite and React Router yourself

The alternative is not another framework so much as the absence of one. A Vite project with React Router gives you the same client-rendered result with a build you fully control. The difference is what happens when you add server rendering. With Vite you add an SSR entry, a server, and a data-loading convention, and you keep every decision. With ice.js the decision is already made and expressed as a plugin, which is faster to start and slower to change.

Compare that with Next.js and the trade-off sharpens. Next.js is the same category of tool, a React framework with file-system routing and multiple rendering modes, and it is the reference point most engineers will reach for. ice.js differs in where the extension points sit: its plugin system is the primary surface, and the examples/icestark-child and examples/icestark-layout directories show microfrontend composition as a supported scenario rather than an integration you write yourself. If your architecture involves mounting several independently built React applications into one shell, that is the specific ground where ice.js has something Next.js does not ship by default. If it does not, the two are close enough that ecosystem and hiring pool decide it, and ice.js is the smaller of the two.

## Licence, maintenance and the cost of upgrading

The licence is MIT, declared in the root package.json and in the LICENSE file at the repository root. MIT imposes essentially no conditions on how you use the output; it does not, however, come with any warranty, and nothing in the repository describes a support commitment or a security response process. That distinction matters more than the licence text itself if you are deploying to production.

Upgrade cost is visible in the repository's tooling. The root package.json wires up changesets with scripts named changeset, version, release, release:beta and release:snapshot, and a .changeset/ directory sits at the top level. That means version bumps and their accompanying notes are generated from changeset files rather than written by hand, so the release notes are the place to look for breaking changes between minor versions. A beta channel and a canary snapshot channel both exist as scripts, which is useful if you want to test a fix before it is tagged, but it also means the published stable line can lag master by a wide margin. Budget for reading changeset entries rather than assuming a minor version is safe.

## Conclusion

Adopt alibaba/ice if you are building a React application that needs SSR or SSG without assembling a bundler, router and server yourself, and you are comfortable with a plugin system that owns your build config. Do not adopt it if you need a framework with a published security policy and a visible release cadence: the README documents no support window, the last push to master was on 2026-04-02, and the newest release listed is v3.6.2 from 2025-06-30. Before committing, verify two things in your own checkout: that the template you pick matches your rendering target, and that the plugin you depend on is published from the packages/ directory rather than living only in examples/.

## FAQ

### How do I install alibaba/ice and create a new ice.js project?

The README recommends create-ice: run npm init ice ice-app --template @ice/lite-scaffold, then cd into the directory, run npm install and npm run start. The development server runs on http://localhost:3000. The npm init initializer form requires npm 6 or later.

### Does ice.js support server-side rendering and static generation?

Yes. The README lists hybrid rendering as a feature, describing pre-rendering pages at build time (SSG) or at request time (SSR). The examples/ directory includes with-first-chunk-cache-ssr and with-data-loader, which are the entries that exercise the rendering and data-loading paths.

### Is alibaba/ice still maintained?

The repository is not archived, and the last push to master was on 2026-04-02. The most recent release listed is v3.6.2 from 2025-06-30, so the published packages lag master by roughly nine months. The README states no support window or security policy.

### What is ice.js licensed under?

MIT. The licence is declared in the root package.json as "license": "MIT" and in the LICENSE file at the repository root. The README repeats the MIT link in its badge row.

## Sources

- [alibaba/ice on GitHub](https://github.com/alibaba/ice)
- [License: MIT](https://github.com/alibaba/ice/blob/master/LICENSE)
- [Project website](https://ice.work)
- [README](https://github.com/alibaba/ice/blob/master/README.md)
- [Releases](https://github.com/alibaba/ice/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alibaba-ice