Skip to content
Get packs

Guide · Open source

How to use ice.js: install, run and render pages

Updated · written with AI from the project's own documentation and checked against our catalogue data

ice.js is an open-source framework built on React for building web applications. This guide shows you how to create a project, start the local development server and understand the main features the project lists, such as file-system routing, state management, data requests and build-time or request-time rendering. It is written for readers who already know React.

ice.jsalibaba/ice · ★ 18.6k · MIT

Quick start

  1. 1Check prerequisites. Make sure Node.js and npm are installed on your machine.
  2. 2Create the project. Run npm init ice ice-app --template @ice/lite-scaffold to generate a new app.
  3. 3Install dependencies. Change into the ice-app folder and run npm install.
  4. 4Start the dev server. Run npm run start and open http://localhost:3000 in your browser.
  5. 5Explore the docs. Read https://ice.work/ for routing conventions, data requests and plugin usage.

What ice.js gives you

ice.js is a framework on top of React. 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 out of the box.

It also covers file-system routing, state management and data requests, and it can pre-render pages at build time (SSG) or at request time (SSR) by default.

  • Zero config: ES6+, TypeScript, Less, Sass and CSS Modules work without manual setup
  • File-system routing, state management and data requests
  • Pre-rendering at build time (SSG) or request time (SSR)
  • A plugin system for reusable solutions from the community
  • The README also mentions web, miniapp and Weex targets, but gives few details on these

How do you install ice.js and create a project?

The README recommends creating a new app with create-ice, which sets up the project for you. Run the command below to create a project from the lite scaffold. You need Node.js and npm; the README notes that the npm init command is available in npm from a certain version onward, so check your npm version if the command is not recognised.

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

How do you run the ice.js dev server?

Move into the new folder, install the dependencies, then start the local server. According to the README, the project runs on http://localhost:3000 once started.

cd ice-app npm install npm run start

How does routing and rendering work in ice.js?

ice.js uses file-system routing, so the structure of your files defines the routes. The README does not go into detail on the folder conventions, so read the docs at https://ice.work/ for the exact rules.

For rendering, the default is hybrid: pages can be pre-rendered at build time (SSG) or on each request (SSR). Choose the mode that fits whether your content changes often or rarely.

What should you check before choosing ice.js?

ice.js assumes you already know React. The README gives little introductory guidance, so beginners may want a React tutorial first. For a static page or a very small script, a framework adds weight you may not need.

If you need a mobile or miniapp target, the README mentions these only briefly, so verify the details in the docs before committing.

  • Good fit: teams that know React and want a ready project structure
  • Good fit: sites that need SSR or build-time rendering
  • Less suited: complete beginners, static pages, tiny scripts
  • Unclear from the README: mobile and miniapp targets

Where can you get help and contribute?

The main documentation is at https://ice.work/. Issues are tracked on GitHub, and there is a Gitter channel for community discussion. Contributions are welcome; the contributing guide is in the repository's CONTRIBUTING.md file.

  • Docs: https://ice.work/
  • Issues: https://github.com/alibaba/ice/issues
  • Gitter: https://gitter.im/alibaba/ice

What people use it for

  • Building a React web app that uses file-system routing and TypeScript from the start
  • Publishing content pages that are pre-rendered at build time with SSG
  • Serving pages rendered on each request with SSR
  • Using Less, Sass or CSS Modules without manual build configuration

Frequently asked questions

Is ice.js free to use?

Yes. ice.js is released under the MIT licence, which the README links to in its LICENSE section. Check the LICENSE file in the repository for the full terms.

What do I need to install ice.js?

The README lists Node.js and npm as prerequisites. You create a project with the npm init command and then install dependencies with npm install.

How do I start an ice.js project?

Create the project with npm init ice ice-app --template @ice/lite-scaffold, then run cd ice-app, npm install and npm run start. The README says the app runs on http://localhost:3000.

Is ice.js good for beginners?

The README is written for developers who already know React and gives little introductory guidance. Beginners should learn the basics of React first.

What are the alternatives to ice.js?

The project lists Next.js, Remix, Umi and Gatsby as comparable projects. Each has its own conventions, so compare them against your project's needs.

What should I do if the dev server does not start?

The README does not include troubleshooting steps. Confirm Node.js and npm are installed, run npm install again, and check the docs at https://ice.work/ or the GitHub issues page.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use ice.js if you already know React and want a ready project structure with TypeScript, styling support and SSR or build-time rendering with little setup. Pick something else if you are new to React, only need a static page or small script, or require a mobile or miniapp target that the README does not explain clearly.

Install options & downloads