wgt-news-ui

基于 Preact 的轻量级资讯卡片组件库，支持 ESM / CJS 双格式，CSS 按需自动注入，零额外样式引入。

目录

• 环境要求
• 本地开发
• 生产构建
• 版本发布
• 安装使用

环境要求

| 依赖 | 版本 | |------|------| | Node.js | >= 14.17 | | npm | >= 6 | | preact（宿主项目提供） | ^10.0.0 |

克隆仓库后先安装依赖：

npm install

本地开发

开发模式使用独立的示例页面（example/），直接读取 src/ 源码，不依赖 dist/，支持热更新。

npm run dev

• 自动打开浏览器，地址：http://localhost:3000
• 监听 src/ 和 example/ 目录，源码保存后自动重新构建并刷新页面
• CSS / Less 以 <style> 标签动态注入，样式修改即时生效无需整页刷新

如果只需构建一次示例页面（不启动服务器），可执行：

npm run build:example

产物输出到 example/dist/bundle.js，直接用浏览器打开 example/index.html 即可预览。

生产构建

生产构建基于 rollup.config.js，会清空并重新生成 dist/ 目录，所有发布内容均来自 dist/。

npm run build

构建过程：

1. 自动执行 clean，删除旧的 dist/ 目录
2. Rollup 同时生成两种格式：
   • dist/esm/ — ES Module 格式，供 Vite / Webpack 等现代打包工具使用，同时生成 .d.ts 类型声明
   • dist/cjs/ — CommonJS 格式，供 Node.js 或旧式打包工具使用
3. 每个组件的 Less 样式经 PostCSS（autoprefixer + cssnano）处理后，输出为组件目录下的独立 style.css，并自动在对应 JS 头部注入 import './style.css'

构建产物结构：

dist/
├── esm/
│   ├── index.js          # ESM 入口
│   ├── index.d.ts        # 类型声明入口
│   ├── types.d.ts        # 全局类型声明
│   └── components/
│       └── NewsCard/
│           ├── index.js  # 组件 JS（含 import './style.css'）
│           ├── index.d.ts
│           └── style.css # 压缩后的组件样式
└── cjs/
    ├── index.js          # CJS 入口
    └── components/
        └── NewsCard/
            ├── index.js
            └── style.css

版本发布

重要：无论发布到内网 Nexus 还是公网 npm，package.json 的 main / module / types / exports 字段均指向 dist/ 目录，且 files 字段只包含 ["dist", "README.md"]，确保消费方引用的永远是构建产物。

发布前检查

package.json 配置了 prepublishOnly 钩子，执行任意 npm publish 前会自动依次运行：

npm run lint  -->  npm run build

无需手动构建，发布命令执行时会自动完成代码检查和生产构建。

发布到内网 Nexus（测试版本）

适用于内部测试，发布到公司私有 Nexus 仓库。

第一步：升级版本号（建议使用预发布标签，与线上版本区分）

# 例：0.1.0 -> 0.1.1-beta.0
npm version prerelease --preid=beta

第二步：发布到内网 Nexus

npm publish --registry http://172.30.10.160:8081/nexus/repository/wgt/

prepublishOnly 钩子会先执行 lint 和 build，发布的是最新构建出的 dist/ 内容。

发布到公网 npm（正式版本）

适用于对外正式发布，发布到 npmjs.com。

第一步：升级正式版本号

# 补丁版本：0.1.0 -> 0.1.1
npm version patch

# 次版本：0.1.0 -> 0.2.0
npm version minor

# 主版本：0.1.0 -> 1.0.0
npm version major

第二步：确认已登录 npm（首次发布需登录）

npm login

第三步：发布

npm publish

默认使用 https://registry.npmjs.org，prepublishOnly 钩子同样会自动执行 lint 和 build。

安装使用

安装

从内网 Nexus 安装：

npm install wgt-news-ui --registry http://172.30.10.160:8081/nexus/repository/npm-group

从公网 npm 安装：

npm install wgt-news-ui

宿主项目需自行安装 Preact（peer dependency）：

npm install preact

使用

直接导入组件即可，无需手动引入任何 CSS 文件，样式会随组件 JS 自动加载。

import { NewsCard } from 'wgt-news-ui';
import type { ICategory, IContent, IEnvMap } from 'wgt-news-ui';

function App() {
  return (
    <NewsCard
      seoCategory={category}
      seoCategoryListData={categoryList}
      seoCategoryListItemData={contentList}
      seoEnvMap={envMap}
    />
  );
}

Props 说明：

| 属性 | 类型 | 说明 | |------|------|------| | seoCategory | ICategory | 当前分类信息 | | seoCategoryListData | ICategory[] | 分类列表数据 | | seoCategoryListItemData | IContent[] | 当前分类下的内容列表 | | seoEnvMap | IEnvMap | 环境变量映射（域名、CDN 等） |

可用脚本

| 命令 | 说明 | |------|------| | npm run dev | 启动开发服务器（热更新，端口 3000） | | npm run build | 生产构建，输出到 dist/（含 clean） | | npm run build:example | 仅构建示例页面，输出到 example/dist/ | | npm run lint | ESLint 检查 src/ 目录 | | npm run lint:fix | ESLint 自动修复 | | npm run format | Prettier 格式化 src/ 下所有文件 |