Developing Components

This chapter will describe how to develop component projects using the Modern.js Module.

Initialize the project

  1. It is recommended to use the @modern-js/create command to initialize an npm project.
Interactive questions
npx @modern-js/create@latest components-project

? Please select the type of project you want to create: Npm Module
? Please fill in the project name: components-demo
? Please select the programming language: TS
? Please select the package manager: pnpm
  1. The initialized directory structure:
.
├── README.md
├── node_modules/
├── dist/
├── modern.config.ts
├── package.json
├── pnpm-lock.yaml
├── src
│   ├── index.ts
│   └── modern-app-env.d.ts
└── tsconfig.json
  1. Finally, modify the file suffix and content of ./src/index.ts as follows, and the initialization of the component project is completed.
./src/index.tsx
export default () => {
  return <div>hello world</div>;
};

Debugging code with Storybook

Please refer to "Using Storybook" to debug code using Storybook.

Developing Styles

Next we can add styles to the component.

The following capabilities are currently supported for developing styles.

  • CSS/PostCSS
  • Less
  • Scss/Sass
  • Tailwind CSS
  • CSS Modules

CSS/PostCSS

Modern.js Module supports PostCSS and has the following built-in PostCSS plugins.

So we can create .css files in our projects and use the syntax support and capabilities provided by these plugins directly in our css files.

  • Source Code:
./src/index.css
a,
b {
  color: red;

  /* "&" comes first */
  & c,
  & d {
    color: white;
  }

  /* "&" comes later, requiring "@nest" */
  @nest e & {
    color: yellow;
  }
}
  • CSS artifact:
./dist/es/index.css
a,
b {
  color: red;
}
a c,
b c,
a d,
b d {
  color: white;
}
e a,
e b {
  color: yellow;
}

Less

Modern.js Module supports development styles using Less.

The current built-in Less version is v4.1.3

  • Source Code:
./src/common.less
@bg: black;
@bg-light: boolean(luma(@bg) > 50%);

div {
  background: @bg;
  color: if(@bg-light, black, white);
}
  • Less artifact:
./dist/es/common.css
div {
  background: black;
  color: white;
}

Sass/Scss

Modern.js Module supports developing styles using Scss/Sass.

The current built-in Sass version is v1.54.4

  • Source code:
./src/common.sass
$font-stack: Helvetica, sans-serif;
$primary-color: #333;

body {
  font: 100% $font-stack;
  color: $primary-color;
}
  • Less artifact:
./dist/es/common.css
body {
  font: 100% Helvetica, sans-serif;
  color: #333;
}

Tailwind CSS

Please refer to "Using Tailwind CSS" for detailed usage.

CSS Modules

Modern.js Module supports the development of styles using CSS Modules. By default, the following files are recognized as CSS Module files.

  • .module.css
  • .module.less
  • .module.scss
  • .module.sass

If you need to configure CSS Modules, you can check out the API at

The following is a code example.

./src/index.tsx
import style from './index.module.css';

export default () => {
  return <div className={style.btn}>hello world</div>;
};
./src/index.module.css
.btn {
  color: blue;
}

Configuring build artifacts

Based on most scenarios of component project usage, it is recommended to use the npm-component build preset. This preset yields a output directory structure of

.
├── dist
│   ├── es
│   ├── lib
│   └── types
  • . /dist/es: Contains bundleless artifacts in ES modules format that support the es6 syntax.
  • . /dist/lib: Contains bundleless artifacts in CommonJS format with support for es6 syntax.
  • . /dist/types: Contains the types file.

The buildPreset can be configured manually if there is a requirement to use syntax support, and supports modifying the supported syntax by adding a suffix to npm-component.

export default defineConfig({
  buildPreset: 'npm-component-es2019',
});

If you have special needs for the build artifacts directory structure, you can use the buildConfig API, which can be used by the following documentation.

Releasing components

It is recommended to use the version release feature provided by Modern.js Module. You can refer to the "Version Management and Release" section for more information.