해당 게시글은 vite v4, typescript v5, react v18, storybook v8, pnpm v8 환경에서 작성되었습니다.

Deploy setting

1. package.json 설정하기

{
  "name": "배포할 패키지 이름",
  "version": "패키지 버전",
  "private": false,
  "description": "패키지 설명",
  "keywords": ["패키지 검색을 도와줄 키워드"],
  "repository": {
    "type": "git",
    "url": "git 주소"
  },
  "license": "MIT", // 라이선스 명시
  "type": "module", // CJS or ESM
  "main": "./dist/index.cjs.js",
  "module": "./dist/index.es.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.es.js",
      "require": "./dist/index.cjs.js"
    }
  },
  "files": ["dist"]
  // ...
}

• version: semantic versioning guidelines를 지켜야 함
• private: true로 설정할 경우 요금 발생
• files: 패키지가 dependency로 설치될 때 포함할 파일을 설정

legacy support

• main: Node.js 12 이전 버전에서 CJS 형식으로 빌드된 메인 파일의 경로
• module: Node.js 12 이전 버전의 ESM 환경에서 사용되는 진입 파일의 경로
• types: TypeScript 4.7 이전 버전의 환경에서 사용되는 타입 정의 파일의 경로

exports

• Node.js v12부터 지원
• 특정 조건, 환경에 따라 다른 모듈을 제공 가능
• ”.”으로 시작하는 상대 경로로 작성

Warning

CJS, ESM을 모두 지원하기 위해서는 Conditional Exports를 사용해야 한다.

 "exports": {
   ".": {
     "require": {
       "types": "./dist/index.d.cts",
       "default": "./dist/index.cjs.js"
     },
     "import": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.es.js"
     }
   }
 },

Trouble Shooting

하지만 Conditional Exports를 설정 후 yarn build를 실행하였을 때에도 dist 폴더 내에 cts 파일이 생성되지 않았다.

=> vite은 CJS build를 더 이상 제공하지 않는다고 한다.

Ref: https://vitejs.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated

2. vite.config.ts 수정하기

타입 정의 파일(.d.ts)를 생성하기 위해 vite-plugin-dts를 설치한다.

yarn add -D vite-plugin-dts

vite.config.ts 전체 코드

export default defineConfig({
  plugins: [
    react(),
    dts({
      insertTypesEntry: true,
    }),
    tsconfigPaths(),
  ],
  build: {
    lib: {
      entry: path.resolve(__dirname, "src/index.ts"),
      name: "@yourssu/design-system-react",
      formats: ["es", "cjs"],
      fileName: format => `index.${format}.js`,
    },
    rollupOptions: {
      external: ["react", "react-dom", "styled-components", "**/*.stories.tsx"],
      output: {
        globals: {
          react: "React",
          "react-dom": "ReactDOM",
          "styled-components": "styled",
        },
        banner: '"use client";',
        interop: "compat",
      },
    },
  },
});

lib

• entry: 진입점, 제공하고자 하는 모든 컴포넌트들을 export하는 부분
• name: 라이브러리 이름 (package.json name과 동일하게하면 된다.)
• formats: 해당 라이브러리를 어떤 모듈 형식으로 빌드할지 설정
• fileName: 출력 파일의 이름을 설정

rollupOptions

• external: 라이브러리에 포함하지 않을 dependency를 명시
• output: 번들 출력에 대한 옵션을 지정
  • globals: 번들링 시 라이브러리 외부에 존재하는 dependency를 제공하기 위해 명시
  • banner: 번들 앞에 해당 문자열을 추가함으로써 모든 컴포넌트들을 클라이언트 컴포넌트로 보장
  • interop: 외부 dependency와의 모듈 간 상호 작용 방식을 설정

3. tsconfig.json 수정하기

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

4. .npmignore 설정하기

npm 배포 시 제외할 파일/폴더를 선택한다.

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*

node_modules
dist-ssr
*.local

# Editor directories and files
.vscode/*
!.vscode/extensions.json
.idea
.DS_Store
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

.yarn
storybook-static
package.tgz
iconsAsset
.storybook

warning

해당 파일이 없다면 .gitignore 폴더를 보게 되는데, .gitignore에는 dist 폴더가 존재하기 때문에 npm에 dist 파일이 올라가지 않는 문제가 생길 수 있으니 주의하자!

This post was written in an environment with vite v4, typescript v5, react v18, storybook v8, and pnpm v8.

Deploy Setting

1. Configuring package.json

{
  "name": "package-name-to-publish",
  "version": "package-version",
  "private": false,
  "description": "package description",
  "keywords": ["keywords to help search for your package"],
  "repository": {
    "type": "git",
    "url": "git-url"
  },
  "license": "MIT",
  "type": "module",
  "main": "./dist/index.cjs.js",
  "module": "./dist/index.es.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.es.js",
      "require": "./dist/index.cjs.js"
    }
  },
  "files": ["dist"]
}

• version: Must follow semantic versioning guidelines
• private: Setting this to true incurs a fee
• files: Specifies which files to include when the package is installed as a dependency

Legacy support

• main: Path to the main CJS-built file for Node.js versions prior to v12
• module: Entry file path for ESM environments in Node.js versions prior to v12
• types: Path to the type definition file for TypeScript versions prior to v4.7

exports

• Supported from Node.js v12
• Allows different modules to be provided based on specific conditions or environments
• Written as relative paths starting with "."

Warning

To support both CJS and ESM, you need to use Conditional Exports:

 "exports": {
   ".": {
     "require": {
       "types": "./dist/index.d.cts",
       "default": "./dist/index.cjs.js"
     },
     "import": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.es.js"
     }
   }
 },

Trouble Shooting

However, even after setting up Conditional Exports and running yarn build, no .cts file was generated in the dist folder.

=> It turns out that Vite no longer provides CJS builds.

Ref: https://vitejs.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated

2. Updating vite.config.ts

Install vite-plugin-dts to generate type definition files (.d.ts).

yarn add -D vite-plugin-dts

Full vite.config.ts:

export default defineConfig({
  plugins: [
    react(),
    dts({
      insertTypesEntry: true,
    }),
    tsconfigPaths(),
  ],
  build: {
    lib: {
      entry: path.resolve(__dirname, "src/index.ts"),
      name: "@yourssu/design-system-react",
      formats: ["es", "cjs"],
      fileName: format => `index.${format}.js`,
    },
    rollupOptions: {
      external: ["react", "react-dom", "styled-components", "**/*.stories.tsx"],
      output: {
        globals: {
          react: "React",
          "react-dom": "ReactDOM",
          "styled-components": "styled",
        },
        banner: '"use client";',
        interop: "compat",
      },
    },
  },
});

lib

• entry: The entry point — the location that exports all components you want to expose
• name: Library name (can match the name in package.json)
• formats: Specifies which module formats the library should be built in
• fileName: Sets the name of the output file

rollupOptions

• external: Specifies dependencies to exclude from the library bundle
• output: Options for the bundle output
  • globals: Declares external dependencies to make available during bundling
  • banner: Prepends this string to the bundle, ensuring all components are treated as client components
  • interop: Configures how the module interacts with external dependencies

3. Updating tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

4. Configuring .npmignore

Select files and folders to exclude from the npm publish.

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*

node_modules
dist-ssr
*.local

# Editor directories and files
.vscode/*
!.vscode/extensions.json
.idea
.DS_Store
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

.yarn
storybook-static
package.tgz
iconsAsset
.storybook

Warning

If this file is absent, npm will fall back to .gitignore, which typically includes dist. This would cause the dist folder to be excluded from the npm package — so be careful!