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.

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

2. 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

3. Finally, modify the file suffix and content of ./src/index.ts as follows, and the initialization of the component project is completed.

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.

• flexbugs-fixes
• custom-properties
• initial
• page-break
• font-variant
• media-minmax
• nesting

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:

a,
b {
  color: red;

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

  /* "&" comes later, requiring "@nest" */
  @nest e & {
    color: yellow;
  }
}

• CSS artifact:

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:

@bg: black;
@bg-light: boolean(luma(@bg) > 50%);

div {
  background: @bg;
  color: if(@bg-light, black, white);
}

• Less artifact:

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:

$font-stack: Helvetica, sans-serif;
$primary-color: #333;

body {
  font: 100% $font-stack;
  color: $primary-color;
}

• Less artifact:

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

• style.autoModules
• style.modules

The following is a code example.

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

export default () => {
  return <div className={style.btn}>hello world</div>;
};

.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.

• modify-output-product
• in-depth-about-build

Testing components#

For more information on how to test components, please refer to "Test project".

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.