Master Frontend Material Development with Iceworks: From Components to Material Collections

What Is Material?

In front‑end development, a material is the smallest reusable unit that can be a component, business component, block, page or application. Components are the building blocks of UI, business components add domain‑specific logic, blocks combine components, pages combine blocks, and an application combines pages.

Why Use Materials?

Materials enable high‑level abstraction, reuse across business domains, and improve maintainability and collaboration. By consolidating domain‑specific materials into a material collection , teams can share and compose UI efficiently.

Material Collection and Project

A material collection groups materials of various granularities. The material project defines the organization of these materials and maps to a front‑end project.

Development Workflow with Iceworks CLI

Iceworks CLI provides commands to initialize a material project, add materials, and publish them. $ iceworks init The project structure includes folders for components, blocks, pages, and scaffolds:

.
├── .eslintrc.js
├── .stylelintrc.js
├── README.md
├── package.json
├── blocks/
│   └── ExampleBlock/
│       └── package.json
├── components/
│   └── ExampleComponent/
│       └── package.json
├── pages/
│   └── ExamplePage/
│       └── package.json
└── scaffolds/
    └── ExampleScaffold/
        └── package.json

Key fields in each material’s package.json are materialConfig for the project and componentConfig for components.

{
  "materialConfig": {
    "template": "@icedesign/ice-react-ts-material-template",
    "type": "react"
  }
}

{
  "componentConfig": {
    "name": "ExampleComponent",
    "title": "demo component",
    "category": "Information"
  }
}

Creating a Business Component

Develop a business component like a regular React component, then run:

$ iceworks add component
$ cd components/ExampleComponent
$ npm install
$ npm run start
$ npm publish

Creating a Page Template

Page templates are written with EJS syntax. Example:

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} />
      <% } %>
    </>
  );
}

Publishing Materials

After development, publish the material package to npm, which hosts the source code and generates a tarball for Iceworks to download. npm publish The material project’s package.json also contains a materialConfig that defines the template and type (React/Vue/Rax).

Generating Material Collection Data

Run the following command at the project root to generate build/material.json containing metadata for all materials.

$ iceworks generate

Using Materials in Iceworks

Install the Iceworks VS Code extension, then set custom material sources in the settings panel. Materials can be searched, added to files, and inserted automatically with dependencies resolved.

Iceworks handles downloading block source code, installing dependencies, and inserting the appropriate import statements.

References

Iceworks CLI – GitHub

Iceworks VS Code Extension – Marketplace

Material Templates – GitHub

Fusion Materials – GitHub