Mastering Material‑Driven Frontend Development with Iceworks

What is a Material? In front‑end development a material is the smallest reusable unit, ranging from DOM nodes and elements to components, base components, business components, blocks, pages, and finally an entire application. Base components are generic UI pieces provided by libraries such as Fusion Design or Ant Design. Business components add domain‑specific logic and are packaged in a business component library.

A block is a higher‑level, self‑contained code fragment that may contain event handling, state management, and data requests; blocks are incorporated into projects by copying source code rather than configuring props. Pages are composed of blocks, and multiple pages together form an application, which is organized as a front‑end project.

Material Collection and Material Project – By aggregating materials of different granularity into a material collection and defining a material project, teams can standardize development patterns and improve maintainability. The material project’s package.json contains a materialConfig field that specifies the template used for initialization.

Iceworks CLI Workflow

# Initialize a material project
$ iceworks init
# Add a single material package
$ iceworks add component   # or block, page, scaffold
# Develop locally
$ npm install
$ npm run start
# Publish the material package
$ npm publish
# Generate material collection data
$ iceworks generate

The project directory follows a conventional layout:

.
├── .eslintrc.js
├── .stylelintrc.js
├── README.md
├── package.json
├── blocks/          # block packages
│   └── ExampleBlock/
│       └── package.json
├── components/       # component packages
│   └── ExampleComponent/
│       └── package.json
├── pages/            # page template packages
│   └── ExamplePage/
│       └── package.json
└── scaffolds/        # scaffold packages
    └── ExampleScaffold/
        └── package.json

Component Development – A component package typically contains README.md, build.json, a demo folder, package.json, source files under src, and a tsconfig.json. The component’s package.json includes an Iceworks‑specific componentConfig with name, title, and category.

Typical commands for a component:

$ iceworks add component
$ cd components/ExampleComponent
$ npm install
$ npm run start   # local debugging
$ npm publish     # publish to npm

Page Template Development – Page templates are stored as source files using EJS syntax. A typical template includes conditional imports, data fetching, and JSX that renders based on template variables defined in config/mock.js and described by a Formily schema in config/settings.json. Example snippet:

import React, { useEffect, useState } from 'react';
<% if (isShowUser) { %>
import User from './components/User';
<% } %>
async function fetchUser() { return { name: 'ICE', age: '18' }; }
export default function() {
  <% if (isShowUser) { %>
  const [user, setUser] = useState({});
  useEffect(() => { async function initUser() { setUser(await fetchUser()); } initUser(); }, []);
  <% } %>
  return (
    <>
      <div>{title}</div>
      <% if (isShowUser) { %>
      <User {...user} />
      <% } %>
    </>
  );
}

After development, the page template is published with npm publish, which runs syntax checks, generates a thumbnail, and uploads the package to npm (or an internal material center) so that Iceworks can fetch it.

Using Materials – Iceworks integrates into VS Code, allowing developers to set custom material sources, search for components, blocks, and pages, and insert them into projects with a single click. The tool automatically downloads source code, installs dependencies, and updates the project files. Material sources can be hosted on npm, Alibaba Material Center, or any CDN that serves the generated material.json file.

References – Iceworks CLI, Iceworks VS Code extension, material templates repository, and public material collections such as Fusion Materials, Miniprogram Materials, and Rax Materials.