基于 CSS Grid 的简易拖拉拽 Vue3 组件，从代码到NPM发布（2）- NPM发布、在线示例

news2025/1/15 16:30:09

这里分享一下本开源项目是如何构建组件库及其如何发布到NPM上的，还有组件库与在线示例的构建有什么差异。

请大家动动小手，给我一个免费的 Star 吧~

大家如果发现了 Bug，欢迎来提 Issue 哟~

github源码

NPM

示例地址

版本更新信息

这两天抽空增加实现了基本的选择、调整大小等交互，欢迎大家理性交流交流哈。

在这里插入图片描述

关于构建

与构建有关的文件，主要有：

└─ dist - 构建的组件库文件
└─ docs - 构建的在线示例网站
└─ src
   └─ main.ts - 在线示例代码入口
└─ index.html - 在线示例HTML入口
└─ package.json - 库信息
└─ tsconfig.build.json - 用于构建组件库配套的类型声明文件
└─ vite.config.ts - 构建配置

关键构建信息与命令，主要有：

package.json

{
  "name": "vue3-grid-drag-resize",
  "version": "0.0.10",
  "type": "module",
  "files": [
    "dist"
  ],
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "homepage": "https://github.com/xachary/vue3-grid-drag-resize",
  "scripts": {
    "build": "run-p type-check \"build-only {@}\" --",
    "build-docs": "run-p type-check \"build-only --mode docs {@}\" --",
    "build-only": "vite build"
  }
}

这里列出了和构建相关的主要信息，大部分都是为了构建 NPM 组件库必须的，指明了：

name 为组件库名称
version 版本信息
dist 为构建后的代码目录
./dist/index.js 为代码入口
./dist/index.d.ts 为类型声明文件
homepage 为显示在 NPM 页面中主页信息

name 必须在 NPM 上唯一的，否则发布会失败。假如非要保留你的命名，可以添加自己的命名空间，例如 @xxx/vue3-grid-drag-resize。
version 每次发布 NPM，必须增加版本号。发布成功后，不能删除，只能 deprecate。

详细看
npm-publish
npm-deprecate

这里有 3 个构建命令：

build 为构建组件库
build-docs 为构建在线示例
build-only 为 vite build 入口

build、build-docs 通过 --mode 传入 vite build，让 vite build 执行不同的构建配置信息，从而构建出 dist、docs 两个不同的目录，dist 为组件库、docs 为在线示例。

vite 构建配置，主要有：

vite.config.ts

// 略

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// 略

import PackageJSON from './package.json'

import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
import dts from 'vite-plugin-dts'

// 略

// https://vitejs.dev/config/
export default defineConfig(({ mode }) => {
  const m = mode === 'docs' ? 'docs' : 'dist'
  console.log('build mode:', m)

  return {
    plugins: [
      vue(),
      ...(m === 'dist'
        ? [
            dts({
              tsconfigPath: './tsconfig.build.json',
              rollupTypes: true
              // insertTypesEntry: true
            })
          ]
        : []),
      cssInjectedByJsPlugin()
    ],
    // 略
    build: {
      outDir: m,
      minify: m === 'dist',
      copyPublicDir: m === 'docs',
      lib:
        m === 'dist'
          ? {
              name: PackageJSON.name,
              entry: fileURLToPath(
                new URL('./src/lib/components/GridDragResize/index.ts', import.meta.url)
              ),
              formats: ['es'],
              fileName: 'index.js'
            }
          : undefined,
      rollupOptions:
        m === 'dist'
          ? {
              external: ['vue'],
              output: {
                globals: {
                  vue: 'Vue'
                }
              }
            }
          : undefined
    },
    // 略
  }
})

上面的 m 即 mode 修饰之后的值，要么是 “dist” 要么是 “docs”，即代表“组件库”和“在线示例”。

关于“plugins”

构建组件库的时候，会增加 vite-plugin-dts 插件的使用，其中 rollupTypes 指的是把左右类型声明都集中到一个声明文件中（最场景），而 tsconfig.build.json 主要是指向从那里开始生成类型声明：

tsconfig.build.json

{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "include": ["src/lib/components/GridDragResize/*"],
  "exclude": ["src/**/__tests__/*"],
  "compilerOptions": {
    "composite": true,
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",

    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

主要关注的是 extends，其余的信息与 tsconfig.app.json 基本一致。

值得注意是，生成的入口，必须 export 所有需要的模块和类型：

src/lib/components/GridDragResize/index.ts

import GridDragResize from './GridDragResize.vue'
import GridDragResizeItem from './GridDragResizeItem.vue'

import './style.less'

export * from './types' // 别忘了 export 模块以外的类型声明

export { GridDragResize, GridDragResizeItem }

组件库样式

上面看到使用一个 vite-plugin-css-injected-by-js 的插件，原因是 vite 默认情况下，构建结果如下：

└─ dist - 构建的组件库文件
   └─ index.d.ts
   └─ index.js
   └─ style.css

一般情况下，通过 import 组件即可，不应该需要额外引入 css 文件，这会造成不便。
所以，使用 vite-plugin-css-injected-by-js 插件后，构建结果变为：

└─ dist - 构建的组件库文件
   └─ index.d.ts
   └─ index.js

此时，css 已经内嵌至 index.js 中。

关于“build”

我分开一下上面的 build 配置：

1、在线示例

build: {
  outDir: 'docs', // 输出目录
  minify: false, // 不 minify
  copyPublicDir: true, // 复制 public 资源
}

vite 默认以 index.html 为入口，在这里无需过多的配置。

2、组件库

    build: {
      outDir: 'dist', // 输出目录
      minify: true, // 需要 minify
      copyPublicDir: false, // 无需复制 public 资源
      lib: {
        name: PackageJSON.name, // 组件库名称
        entry: fileURLToPath(
          new URL('./src/lib/components/GridDragResize/index.ts', import.meta.url)
        ), // 组件库代码入口
        formats: ['es'], // 只构建 es 版本
        fileName: 'index' // 构建后的文件名
      },
      // 排除 vue 库代码
      rollupOptions: {
        external: ['vue'],
        output: {
          globals: {
            vue: 'Vue'
          }
        }
      }
    }