diff --git a/docs/.note/.note.md b/docs/.note/.note.md deleted file mode 100644 index ece1926..0000000 --- a/docs/.note/.note.md +++ /dev/null @@ -1,31 +0,0 @@ - -- [开发一款 Node CLI 终端工具](https://juejin.cn/post/7178666619135066170) -- https://zhuanlan.zhihu.com/p/105846231 (https://github.com/NuoHui/easy-cli) -- [详解前端脚手架开发](https://juejin.cn/post/6847902225025466376) -- [走进Vue-cli源码,自己动手搭建前端脚手架工具](https://segmentfault.com/a/1190000013975247) -- [NuoHui/easy-cli](https://github.com/NuoHui/easy-cli) - - -## create流程 - -### 解析命令行参数 - -### 配置指令命令 - -### 创建项目目录 - - -### 用户预设 - -### 拉取项目 - -### 模板编译 -- metalsmith : 静态网站生成器 -- consolidate : 支持各种模板引擎的渲染 -- handlebars : 模板引擎 - - -## gulp plugins -- https://github.com/alferov/awesome-gulp -- https://github.com/Pines-Cheng/awesome-gulp-cn - diff --git a/docs/.note/index.md b/docs/.note/index.md deleted file mode 100644 index 0f2ac7d..0000000 --- a/docs/.note/index.md +++ /dev/null @@ -1,21 +0,0 @@ - -pipflow -基于gulp的前端开发工作流 (旨在使web应用程序的开发/构建流程变得更简单。) -内置合并、编译、打包、压缩等功能,极大简化前端开发流程。 - - - -## feature - -开箱即用 : 通过pipflow命令快速创建项目,无需编写冗长的gulp配置代码 -高效性能(轻量快速) : 优化gulp任务,缓存已通过的文件信息以实现增量构建 -功能丰富: 内置一整套构建流程和多类型构建任务,实现资源的自动化处理 - -可配置 - 通过简单的配置即可自定义构建过程,调整任务顺序等。 -可扩展 - 可以根据需求轻松扩展现有任务功能或自定义新任务 -多环境支持 - 设置运行模式, 可以在开发环境和生产环境之间轻松切换 - - - -1. 开发者只需要通过简单的命令就可以运行这些自动化任务,无需编写冗长的gulp配置文件。它极大地简化了基于gulp的前端项目构建过程。 -2. pipflow-CLI还提供了方便的初始化向导,可以快速帮助开发者创建一个组织良好的项目结构。它遵循了通用的最佳实践,让开发者可以快速进入编码状态。 \ No newline at end of file diff --git "a/docs/.note/\344\277\241\346\201\257.md" "b/docs/.note/\344\277\241\346\201\257.md" deleted file mode 100644 index 73a110a..0000000 --- "a/docs/.note/\344\277\241\346\201\257.md" +++ /dev/null @@ -1,99 +0,0 @@ - -帮我写一段关于`pipflow-CLI`的描述,它是一个基于gulp工作流的命令行工具。 - -`pipflow` -A web developer workflow based on Gulp. It has built-in merging, compilation, and compression features that greatly simplify front-end development. -基于gulp的前端开发工作流。它内置了诸如合并、编译、打包、压缩等功能,极大地简化了前端开发流程。 - -`pipflow-cli` -A command-line tool based on Gulp-workflow that quickly build web development workflows. -基于gulp的命令行工具,可快速搭建web开发工作流程,并支持功能定制化。 - - - ---- - - -帮我写一段关于`pipflow-CLI`的描述,它是一个基于gulp工作流的命令行工具。 - -`pipflow` -A web developer workflow based on Gulp. It has built-in merging, compilation, and compression features that greatly simplify front-end development. -基于gulp的前端开发工作流。它内置了诸如合并、编译、打包、压缩等功能,极大地简化了前端开发流程。 - -`pipflow-cli` -A command-line tool based on Gulp-workflow that quickly build web development workflows. -基于gulp的命令行工具,可快速搭建web开发工作流程,并支持功能定制化。 - - - - -pipflow-CLI是一个基于gulp工作流的命令行工具,它可以大大简化前端开发流程。pipflow-CLI提供了一组开箱即用的gulp任务和功能,开发者无需从零开始配置就可以立即启动前端项目的开发。 - -pipflow-CLI的主要功能包括: - -- 处理less/sass,自动添加浏览器前缀,压缩CSS -- 合并、压缩、校验JavaScript文件 -- 优化图片,生成雪碧图 -- 实时重新加载浏览器 -- 生成HTML/CSS/JS的sourcemap -- 本地服务器,支持HTTPS和浏览器同步测试 -- 多页面应用生成 -- 错误通知 -- 自定义gulp任务 - -通过pipflow-CLI,开发者可以专注于代码编写,无需浪费时间在重复的工程配置上。它使用简单的命令就可以完成复杂的前端构建流程,极大地提高了开发效率。pipflow-CLI是一个非常适合前端开发者的命令行助手。 - - -pipflow-CLI is a command line tool based on the gulp workflow. It can greatly simplify front-end development workflows. pipflow-CLI provides a set of out-of-the-box gulp tasks and functions, so developers can start front-end project development immediately without configuring from scratch. - -The main features of pipflow-CLI include: - -- Processing Less/Sass, autoprefixing, compressing CSS -- Concatenating, compressing, linting JavaScript files -- Optimizing images, generating sprites -- Live reloading in browser -- Generating HTML/CSS/JS sourcemaps -- Local server, supports HTTPS and browser sync testing -- Multi-page app builds -- Error notification -- Custom gulp tasks - -With pipflow-CLI, developers can focus on coding without wasting time on repetitive engineering configurations. It uses simple commands to complete complex front-end build workflows, greatly improving development efficiency. pipflow-CLI is a very handy command line assistant for front-end developers. - - - - - -------- - - - - -pipflow-CLI是一个基于gulp的命令行工作流工具。它可以帮助web开发者更方便地管理前端项目的构建和自动化任务。 - -pipflow-CLI提供了一系列常用的gulp任务预设,让开发者无需自己从零配置就可以立即使用gulp。它内置了诸如编译Less/Sass、CSS自动添加浏览器前缀、JavaScript压缩、图片优化等功能。 - -使用pipflow-CLI,开发者只需要通过简单的命令就可以运行这些自动化任务,无需编写冗长的gulp配置文件。它极大地简化了基于gulp的前端项目构建过程。 - -此外,pipflow-CLI还提供了方便的初始化向导,可以快速帮助开发者创建一个组织良好的项目结构。它遵循了通用的最佳实践,让开发者可以快速进入编码状态。 - -总的来说,pipflow-CLI是一个轻量级但强大的gulp工作流工具,可以帮助web开发者提高工作效率,构建健壮的前端项目。它的简单易用和预设功能,使其成为基于gulp工作流的理想选择。 - - ------ - - -pipflow-CLI是一款基于gulp工作流的命令行工具。它以高效、灵活、可扩展的特性,深受开发者的喜爱。这款工具不仅能够帮助开发者快速构建和管理项目,还融合了gulp的强大流程控制功能,让开发者在处理复杂任务时轻松应对。 - -特性 -- 基于gulp工作流: 利用gulp的强大功能,pipflow-CLI可以流畅地处理文件和数据,提供丰富的插件支持,使开发者可以根据项目需求定制工作流。 -- 命令行工具: 作为一个命令行工具,pipflow-CLI可以在终端中轻松执行,方便开发者在任何环境下都能高效地进行项目构建和管理。 -- 高效性能: 通过gulp的流处理方式,pipflow-CLI确保了任务运行的高效性,节省开发者的宝贵时间。 -- 扩展性强: pipflow-CLI的设计使其易于扩展,开发者可以根据需要添加新的功能和命令,使其更好地适应项目需求。 - -无论你是在构建大型项目还是进行日常的开发任务,pipflow-CLI都能为你提供强大的支持,使你的开发过程更加顺畅。 - ----- - -Pipflow-CLI是一个基于Gulp工作流的命令行工具,它可以帮助开发者更高效地管理和构建项目。通过使用Pipflow-CLI,开发者可以通过简单的命令行指令来执行各种任务,例如构建、打包、编译、压缩等。Pipflow-CLI提供了一系列的插件和任务,可以方便地集成到项目中,并且可以根据项目的需要进行定制。使用Pipflow-CLI可以大大简化项目的构建流程,提高开发效率和代码质量。同时,Pipflow-CLI还提供了丰富的文档和示例,方便开发者快速上手和使用。如果你正在寻找一个高效、灵活、易用的构建工具,那么Pipflow-CLI绝对是一个值得尝试的选择。 - diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index ae1c089..d89ade7 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -1,9 +1,14 @@ import { defineConfig } from 'vitepress' +import { version } from '../../packages/main/package.json' +const ogTitle = 'pipflow' +const ogDescription = 'A web developer workflow based on Gulp. 基于gulp工作流的前端构建工具. 开箱即用,无需配置即可启动web项目的开发.' +const ogUrl = 'https://pipflow.mengqing.org' + // https://vitepress.dev/reference/site-config export default defineConfig({ - title: "pipflow", - description: "A web developer workflow based on Gulp. It has built-in merging, compilation, and compression features that greatly simplify front-end development.", + title: ogTitle, + description: ogDescription, lang: 'zh-CN', locales: { @@ -14,14 +19,26 @@ export default defineConfig({ lastUpdated: true, sitemap: { - hostname: 'https://pipflow.mengqing.org' + hostname: ogUrl }, + /* prettier-ignore */ + head: [ + // ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }], + // ['link', { rel: 'icon', type: 'image/png', href: '/favicon.png' }], + ['meta', { name: 'theme-color', content: '#ea4a4a' }], + ['meta', { name: 'og:type', content: 'website' }], + ['meta', { name: 'og:locale', content: 'zh-CN' }], + ['meta', { name: 'og:site_name', content: ogTitle }], + // ['meta', { name: 'og:image', content: 'https://vitepress.dev/vitepress-og.jpg' }], + ['meta', { name: 'og:url', content: ogUrl }], + ], + themeConfig: { // https://vitepress.dev/reference/default-theme-config editLink: { - pattern: 'https://github.com/meqn/pipflow-cli/edit/main/docs/:path', + pattern: 'https://github.com/meqn/pipflow/edit/main/docs/:path', text: '为此页提供修改建议' }, @@ -39,8 +56,15 @@ export default defineConfig({ }, nav: [ - { text: '指南', link: '/guide/' }, - { text: '配置', link: '/config/' } + { text: '指南', link: '/guide/', activeMatch: '/guide/' }, + { text: '配置', link: '/config/', activeMatch: '/config/' }, + { text: '常见问题', link: '/help', activeMatch: '/help' }, + { + text: `v${version}`, + items: [ + { text: 'Changelog', link: 'https://github.com/Meqn/pipflow/releases' }, + ] + } ], sidebar: { @@ -63,6 +87,7 @@ export default defineConfig({ { text: 'Javascript', link: '/guide/task-script' }, { text: 'CSS', link: '/guide/task-style' }, { text: '静态资源', link: '/guide/task-assets' }, + { text: 'server服务', link: '/guide/task-server' }, { text: '自定义任务和流程', link: '/guide/task-user' }, { text: '其他', link: '/guide/task-more' } ] @@ -73,7 +98,7 @@ export default defineConfig({ }, { text: '常见问题', - link: '/guide/help', + link: '/help', } ], '/config/': [ diff --git a/docs/config/build-options.md b/docs/config/build-options.md index 7159162..a165621 100644 --- a/docs/config/build-options.md +++ b/docs/config/build-options.md @@ -78,6 +78,6 @@ CSS压缩是基于 `cssnano` 插件, 详细配置请参见 [这里](https://cssn 图片压缩是基于 `gulp-imagemin` 插件, 详细配置请参见 [这里](https://www.npmjs.com/package/gulp-imagemin)。 -::: danger 🚨 提醒 +::: warning 🚨 提醒 由于安装 `gulp-imagemin` 依赖经常失败(国内环境),且图片压缩是一项耗时的一次性任务。所以 `pipflow` 将 `gulp-imagemin` 的安装提取到项目的依赖中。如果你的项目不需要 压缩图片或者手动一次性压缩,请删除项目的 `package.json` 中的 `gulp-imagemin` 依赖,并将 `imageMinify` 配置项的值设置为 `false`。 ::: diff --git a/docs/config/task-options.md b/docs/config/task-options.md index fd709e3..9489c4e 100644 --- a/docs/config/task-options.md +++ b/docs/config/task-options.md @@ -111,9 +111,9 @@ interface CompilerOptions { ``` 每个预处理器支持的选项可以在它们各自的文档中找到: -- `sass/scss` : [选项]() -- `less` : [选项]() -- `stylus` : [选项]() +- `sass/scss` : [配置说明](https://www.npmjs.com/package/gulp-sass) +- `less` : [配置说明](https://www.npmjs.com/package/gulp-less) +- `stylus` : [配置说明](https://www.npmjs.com/package/gulp-stylus) 示例: @@ -184,8 +184,9 @@ module.exports = { 在 `serve` 阶段是否监视文件变动并重新编译、刷新页面。 +支持 `'html', 'style', 'script', 'static', 'image', 'copy', 'user'` 类型任务。 - + \ No newline at end of file diff --git a/docs/guide/cli.md b/docs/guide/cli.md index f40c1c7..6ee96b9 100644 --- a/docs/guide/cli.md +++ b/docs/guide/cli.md @@ -202,8 +202,9 @@ Options: ### `pipflow server` {#cli-server} -启动一个本地HTTP服务器。它是基于 BrowserSync 的。 -你可以在任何目录下运行该命令,无需其他配置。 +快速启动一个本地HTTP服务器,用于预览或演示单个 HTML 页面。它是基于 `BrowserSync` 实现的。 + +无需配置,可在任意目录启动服务器,同时也支持参数自定义,如端口、目录、是否监听文件变化、浏览器自动刷新等。 #### 使用 ```bash diff --git a/docs/guide/help.md b/docs/guide/help.md deleted file mode 100644 index 38c71f4..0000000 --- a/docs/guide/help.md +++ /dev/null @@ -1,18 +0,0 @@ -# 常见问题 - - - -## 安装依赖时间过长 - -1. 设置 .mpmrc - -2. 使用 cnpm - -我把部分依赖包抽离到外部,如果项目中不使用的话,可以直接删除。 -1. 图片压缩 - 删除package.json中的 `gulp-imagemin` 依赖 - 设置 `imageMinify` 为 false - -## 安装依赖失败 -经常碰到安装依赖失败,多数是因为网络原因:很多包将源码托管在 s3 服务器上,国内可能会被墙。 - diff --git a/docs/guide/task-assets.md b/docs/guide/task-assets.md index 240adb9..75956ad 100644 --- a/docs/guide/task-assets.md +++ b/docs/guide/task-assets.md @@ -1,41 +1,43 @@ -# 静态资源 +# 静态资源任务 {#assets-task} -## 静态文件任务 +任务类型为 `static` 或 `image` 。 +静态资源包含常见的图像、媒体和字体文件等。如果不想处理这些静态资源文件,你可以将它们放在 `public` 目录下。 -## 图片任务 -### 图片压缩 -由于图片压缩是一个耗时任务,且 `gulp-imagemin` 插件**安装依赖经常失败**(国内环境)。鉴于此会影响整个工程的安装运行,所以 `pipflow` 并未内置图片压缩功能,如果需要则手动安装依赖并引入插件即可。 +## 任务流程 {#process-flow} -**具体步骤如下:** +- 自定义处理流程 - 处理 `pipflow.config.js` 中添加的自定义 `plugins` +- 压缩图片 - 基于 `imagemin` 压缩图片 +- 生成文件hash及manifest文件 -1. 安装 `gulp-imagemin` 依赖 -```shell -npm install -D gulp-imagemin@7 -``` -::: warning 注意 -`gulp-imagemin` 只能安装 `<=7` 的版本,`8`及以上版本仅支持 `esModule` 模块化. -::: +## 图片压缩 -2. 在 `pipflow.config.js` 中找到当前任务,并加入以下代码 +由于图片压缩是一项耗时的一次性任务,且 `gulp-imagemin` 插件**安装依赖经常失败**(国内环境)。所以 `pipflow` 将 压缩图片作为一个可选项。如果你的项目不需要 压缩图片或者手动一次性压缩,请删除项目的 `package.json` 中的 `gulp-imagemin` 依赖,并将 `imageMinify` 配置项的值设置为 `false`。 -```js -const imagemin = require('gulp-imagemin') +关于图片压缩配置,你可以为所有静态任务统一配置,也可以单独配置某个静态任务。 -module.exports = { - tasks: [ - { - type: 'assets', - plugins: [ - imagemin(/* options */) - ] - } - ] +1. 统一配置项 `build.imageMinify` , 具体请看 [这里](../config/build-options.md#build-imageminify)。 +2. 单独任务配置项 `minify`。 + +```ts +ImageMinifyOptions : boolean | { + plugins?: ImageMinifyPlugin[] + options?: { + verbose?: boolean + silent?: boolean + } } ``` -> `gulp-imagemin` 插件在压缩图片过程中会自动过滤非图片文件。 请[点击查看文档](https://www.npmjs.com/package/gulp-imagemin) \ No newline at end of file + + +> `gulp-imagemin` 插件在压缩图片过程中会自动过滤非图片文件。 具体配置请点击 [这里](https://www.npmjs.com/package/gulp-imagemin) + +::: warning 🚨 提醒 +`gulp-imagemin` 只能安装 `<=7` 的版本,`8`及以上版本仅支持 `esModule` 模块化. +::: + diff --git a/docs/guide/task-html.md b/docs/guide/task-html.md index 0221602..7cfc2a1 100644 --- a/docs/guide/task-html.md +++ b/docs/guide/task-html.md @@ -1,6 +1,9 @@ # HTML 任务 -## 处理流程 {#process-flow} +任务类型为 `html` 。 + + +## 任务流程 {#process-flow} - 环境变量处理 - 环境变量在构建时会被静态替换 - 模板渲染 - 渲染HTML模板引擎,支持 `Pug`, `EJS`, `Handlebars`, `Nunjucks`, `art-template` diff --git a/docs/guide/task-more.md b/docs/guide/task-more.md index 0695ed5..7bbbac8 100644 --- a/docs/guide/task-more.md +++ b/docs/guide/task-more.md @@ -1,24 +1,69 @@ -# 其他任务 +# 其他任务 {#more-task} +下面是一些辅助任务,用于复制、压缩 和 删除 文件及目录等。 -## ZIP压缩任务 (archive) +## copy 复制任务 {#copy-task} -```bash -pipflow pack [options] +`copy` 任务用于复制文件和目录。 -# example -pipflow pack dist/ dist.zip -# 将 `dist/` 目录打包, 压缩包 `dist.zip`在项目的根目录 +```js +// pipflow.config.js +module.exports = { + tasks: [ + { + type: 'copy', + input: 'src/assets/**/*', + dest: 'dist/assets/' + } + ] +} +``` + +这会将 `src/assets/` 目录下的所有文件复制到 `dist/assets/`。 + +> copy任务支持 `glob` 写法来匹配文件,可以配置 `input` 和 `dest` 路径来定义复制源和输出目标。如果源文件是目录,会将整个目录复制过去。 + + +## remove 删除任务 {#remove-task} + +`remove` 任务用于删除文件和目录。 -pipflow pack public/favicon.ico src/ dist/source.zip -# 将 `ico`文件 和 `src/` 目录打包, 压缩包 `source.zip`在dist目录中 +```js +// pipflow.config.js +module.exports = { + tasks: [ + { + type: 'remove', + input: 'dist/**/*.map' + } + ] +} ``` -### options -最后一项是打包输出的路径,其他项目是打包的目标路径。 +这会删除 `dist` 目录下所有的 `.map` 文件。 +`input` 同样支持 `glob` 写法。 + + +## archive 压缩任务 {#archive-task} + +`archive` 任务用于文件和目录的压缩和打包。 + +```js +// pipflow.config.js +module.exports = { + tasks: [ + { + type: 'archive', + input: 'dist/**/*', + dest: 'release.zip' + } + ] +} +``` +这会将 `dist` 目录下的所有文件和目录打包压缩成 `release.zip`。 diff --git a/docs/guide/task-script.md b/docs/guide/task-script.md index 2ee03a7..b215013 100644 --- a/docs/guide/task-script.md +++ b/docs/guide/task-script.md @@ -1,7 +1,8 @@ -# script 任务 +# script 任务 {#script-task} +任务类型为 `script` 。 -## 处理流程 {#process-flow} +## 任务流程 {#process-flow} - 环境变量处理 - 环境变量注入 - 别名替换 - 静态替换 `alias` 对应的字符串 diff --git a/docs/guide/task-server.md b/docs/guide/task-server.md index 3bfd6f0..cdcffa0 100644 --- a/docs/guide/task-server.md +++ b/docs/guide/task-server.md @@ -12,7 +12,10 @@ pipflow dev ``` -如果你的项目是基于 `pipflow create` 创建的,无需任何配置,直接运行 `npm run dev` 命令即可启动本地开发服务器。它会自动解析工程配置,实现工程目录的本地开发和调试。具有文件监听、浏览器自动刷新、CSS注入、反向代理等开发辅助功能。 +本地开发服务通过 `pipflow dev` 命令启动,提供了文件监听、浏览器自动刷新、CSS 注入等功能,方便项目开发和调试。 + +如果是通过 `pipflow create` 创建的项目,无需任何配置,直接执行 `npm run dev` 即可启动开发服务器。 + ## 本地预览服务 {#preview-server} @@ -21,7 +24,10 @@ pipflow dev pipflow task server --preview ``` -基于 `pipflow` 创建的项目,可以通过 `npm run preview` 命令便可预览生产构建产物,默认将构建目录作为静态文件服务器目录。 +本地预览服务通过 `pipflow task server --preview` 启动,用于预览生产环境构建后的静态资源。 + +基于 `pipflow` 创建的项目,可以通过 `npm run preview` 快速预览构建产物 (服务器目录默认为构建目录)。 + ## 快速预览服务 {#quick-server} @@ -30,13 +36,12 @@ pipflow task server --preview pipflow server ``` -`pipflow` 提供了一个快速启动本地 HTTP 服务的命令。 +快速预览服务通过 `pipflow server` 命令启动,用于快速预览或演示单个 HTML 页面。 -如果全局安装了 `@pipflow/cli`,无需任何配置,运行 `pipflow server` 命令即可在任意目录中快速启动一个server服务。主要用来快速预览或演示单个HTML文件。 也可以指定目录、端口、监听文件变化、开启浏览器自动刷新等参数。 +全局安装 `@pipflow/cli` 后,无需配置,可在任意目录启动服务器,同时也支持参数自定义,如端口、目录、是否监听文件变化、浏览器自动刷新等。 -具体配置请参见 [这里](../config/server-options.md)。 ::: tip 提示 -由于以上3种内置 server服务 已经覆盖了大部分的场景,所以不建议在 `pipflow.config.js` 配置文件中创建新的 server任务。 +以上 3 种服务器已覆盖大部分场景,一般无需在配置文件中自行配置 server 任务。 ::: diff --git a/docs/guide/task-style.md b/docs/guide/task-style.md index 6494429..8c6f89f 100644 --- a/docs/guide/task-style.md +++ b/docs/guide/task-style.md @@ -1,10 +1,168 @@ # style 任务 -## 处理流程 +任务类型为 `style` 。 + +`style` 任务用于处理 CSS 资源,主要包含 CSS 预处理、兼容性处理、压缩等功能。 + + +## 任务流程 {#process-flow} + +- 环境变量替换 - 静态替换 `env` 对应的字符串 +- 别名替换 - 静态替换 `alias` 对应的字符串 +- CSS 预处理器编译 +- 自定义插件处理 +- postcss 处理 - 包含 属性兼容性前缀(autoprefixer)、压缩混淆(cssnano)等 +- 生成 source map 文件 +- 生成文件hash - 支持 `[name]-[hash]` 和 `[name]?[hash]` 两种方式。 + +## 文件入口 {#file-entry} + +文件入口配置支持 单一字符串,数组,和对象 3 种方式。 + +```js +// 1. 字符串 +{ + input: './src/styles/**/*.{css,scss}' +} + +// 2. 数组方式 +{ + input: [ + './src/styles/comm.css', + './src/styles/index.css', + './src/styles/page.css', + ] +} + +// 3. 对象方式 +{ + input: { + 'comm/index': [ + './src/styles/base.css', + './src/styles/utils.css', + ], + 'index': './src/styles/index.css', + 'pages': './src/styles/pages/*.css' + } +} +``` + ## CSS 预处理器 {#css-preprocessor} -## postcss集成 -### remtopx +pipflow 支持 `sass (scss)`, `less`, `stylus` 三种最常见的 CSS 预处理器。你只需在 `style` 类型任务的 `compiler` 属性中配置对应的预处理器即可。 + +为了编码方便,你还可以在转译时注入额外代码。 + +下面我们以 `scss` 为例进行简单配置: + +```js +// pipflow.config.js +module.exports = { + tasks: [ + // ... 其他任务 + { + type: 'style', + input: './src/styles/**/*.scss', + compiler: 'sass', + compilerOptions: { + // 注入额外代码 + additionalData: `@import './comm/variables';\n$--primary-color: blue;`, + // sass 选项 + preprocessorOptions: { + includePaths: ['node_modules'], //支持加载npm包 + } + } + } + ] +} +``` + +::: tip additionalData 选项 +所有预处理器都支持 `additionalData` 选项,可以用于为每个样式内容注入额外代码。请注意,如果注入的是实际的样式而不仅仅是变量时,那么这些样式将会在最终的打包产物中重复出现。 +::: + + +各预处理器使用详见: +- `sass/scss` : [配置说明](https://www.npmjs.com/package/gulp-sass) +- `less` : [配置说明](https://www.npmjs.com/package/gulp-less) +- `stylus` : [配置说明](https://www.npmjs.com/package/gulp-stylus) + + +## PostCSS 插件 {#postcss-plugins} + +PostCSS 内置了众多插件用来转换 CSS, 你只需在项目的 `postcss.config.js` 文件中配置即可。目前 `pipflow` 已内置浏览器兼容性前缀(`postcss-preset-env`)和压缩优化(`cssnano`)插件。 + +这里列出一些常用的插件和用法示例,更多插件请参见 [这里](https://github.com/postcss/postcss) + ### pxtorem -### pxtoview \ No newline at end of file + +将 `px` 单位转换为 `rem` 单位。 更多配置请参见 [这里](https://github.com/cuth/postcss-pxtorem) + +```js +// postcss.config.js +module.exports = { + plugins: [ + require('postcss-pxtorem')({ + rootValue: 16, + propList: ['*'], + minPixelValue: 12, + exclude: /node_modules/i, + }) + ] +} +``` +### pxtoview + +将CSS中的 `px` 单位转换为 `vw、vh` 等视口单位。 更多配置请参见 [这里](https://github.com/evrone/postcss-px-to-viewport) + +```js +const px2viewport = require('postcss-px-to-viewport') + +module.exports = { + plugins: [ + require('postcss-px-to-viewport')({ + viewportWidth: 375, + unitPrecision: 5, + viewportUnit: 'vw', + propList: ['*'], + selectorBlackList: ["ignore"], + minPixelValue: 1, + mediaQuery: false + }) + ] +} +``` + +### with Tailwind CSS + +项目中集成 `Tailwind CSS`。 具体配置请参见 [这里](https://tailwindcss.com/docs/installation/using-postcss) + +1. 通过 `npm` 安装 `tailwindcss` 及其依赖项,并创建 `tailwind.config.js` 文件。 + +```bash +npm install -D tailwindcss autoprefixer +npx tailwindcss init +``` + +2. 配置 `tailwind.config.js` +```js +/** @type {import('tailwindcss').Config} */ +module.exports = { + content: ["./src/**/*.{html,js}"], + theme: { + extend: {}, + }, + plugins: [], +} +``` + +3. 配置 `postcss.config.js` +```js +module.exports = { + plugins: [ + require('tailwindcss'), + require('autoprefixer') + ], +} +``` diff --git a/docs/guide/task-user.md b/docs/guide/task-user.md index 2d6fc25..b970c8b 100644 --- a/docs/guide/task-user.md +++ b/docs/guide/task-user.md @@ -1,16 +1,17 @@ # 自定义任务和流程 + ## 扩展任务 {#extend-task} 对于已有的任务,如果不满足你的业务需求,你可以通过这个任务的 `plugins` 配置项来扩展当前任务。 -比如,`html` 类型的任务默认处理流程会包含 模板引擎渲染、字符串内容替换、输出压缩、.... 等流程。如果你想在 html 类型任务中增加其他处理流程,可以通过 `plugins` 配置项来扩展任务。 +例如,`html` 类型的任务默认处理流程包括 模板引擎渲染、字符串内容替换、资源文件指纹、输出压缩等流程。如果你想在 `html` 类型任务构建过程中增加其他处理流程,你可以这样配置: -示例: -在默认流程之外,动态插入一段html源码 +比如在默认流程之外,动态插入一段 jquery外链源码 ```js +// pipflow.config.js const { defineConfig } = require('pipflow') -const replace = require('gulp-replace') +const dom = require('gulp-dom') module.exports = defineConfig({ tasks: [ @@ -18,7 +19,12 @@ module.exports = defineConfig({ type: 'html', input: './src/**/*.html', plugins: [ - // gulp-dom 插入代码 + dom(function() { + return this.querySelectorAll('body')[0].insertAdjacentHTML( + 'beforeend', + '' + ) + }) ] } ] @@ -27,29 +33,49 @@ module.exports = defineConfig({ ## 创建新任务 {#create-task} -创建一个新任务非常简单,你只需要在配置文件`pipflow.config.js`的`tasks`中增加一条任务项即可。 +创建一个新任务非常简单,你只需要在配置文件 `pipflow.config.js` 的 `tasks` 中增加一条任务项即可。 -pipflow的任务类型主要分为两大类: +`pipflow` 的任务类型主要分为两大类: -- 固定流程任务:内置了基础的处理流程的任务。 +- 固定流程任务:内置了基础处理流程的任务。 - 自定义流程任务:无内置流程,处理过程完全自主控制。 -### 1. 固定流程任务 +### 1. 创建固定流程任务 当任务类型不为 `user` 时为固定流程任务。 +下面我们来创建一个使用 `mustache` 模板引擎(未内置) 的 `html` 类型任务。 + ```js -// html 其他模板引擎任务 +// pipflow.config.js +const { defineConfig } = require('pipflow') +const mustache = require('gulp-mustache') + +module.exports = defineConfig({ + tasks: [ + { + type: 'html', + input: './src/**/*.html', + plugins: [ + mustache({ + title: 'Hello, Pipflow!', + }) + ] + } + ] +}) ``` -### 2. 自定义流程任务 -当任务类型为 `user` 时为自定义流程任务。创建自定义流程任务的方式有两种: +是不是非常简单?😀 😃 😄 😁 😆 + +### 2. 创建自定义流程任务 +当任务类型为 `user` 时为自定义流程任务。创建自定义流程任务有两种方式: - `plugins` 方式 - `compiler` 方式 这两种方式除了书写方式不同之外,没有其他区别。 -#### 2.1 plugins 方式 +#### 2.1 `plugins` 方式 将处理流程写在 `plugins` 配置中。 ```js @@ -60,6 +86,7 @@ const concat = require('gulp-concat') module.exports = { tasks: [ { + name: 'build:css', type: 'user', plugins: [ gulp.src('./src/**/*.css', { base: './src' }), @@ -71,7 +98,7 @@ module.exports = { } ``` -或者,你可以简化成如下形式 +或者,你可以简化为如下形式 ```js // pipflow.config.js @@ -91,11 +118,11 @@ module.exports = { ``` ::: tip -你如果配置了 `input` 属性,在gulp的处理过程中会自动增加文件的输入流和输出流。你只需要在`plugins`中配置处理流程所需要的插件即可。 +如果配置了 `input` 属性,在gulp的处理过程中会自动增加文件的输入流和输出流。你只需要在`plugins`中配置处理流程所需要的插件即可。 ::: -#### 2.2 compiler 方式 +#### 2.2 `compiler` 方式 将 `compiler` 作为一个任务函数。它和定义一个gulp任务是一样的。 ```js @@ -159,7 +186,7 @@ module.exports = defineConfig({ ::: tip 入口说明 在 `compose` 任务中,`input`入口和其他类型任务有些不同,其 `input` 值是一个二维数组 `string[][]`,数组的每一项是一个任务名。 -`input` 的值转换后的结果: +下面是 `input` 的值转换后的结果: ```js series(parallel('任务名', ...), parallel(...), ...) ``` diff --git a/docs/guide/task.md b/docs/guide/task.md index fa42843..a5791aa 100644 --- a/docs/guide/task.md +++ b/docs/guide/task.md @@ -4,18 +4,27 @@ 主要任务类型包含: -- `html` - HTML处理任务 -- `script` - JavaScript处理任务 -- `style` - CSS处理任务 -- `static` - 静态资源处理任务 -- `image` - 图片资源处理任务 -- `server` - 创建本地服务器任务 +- `html` - HTML处理任务,可用于 `HTML` 文件的语法检查、模板渲染、压缩等 +- `script` - JavaScript处理任务,可用于 JavaScript 文件的语法检查、美化、压缩、打包等 +- `style` - CSS处理任务,可用于 CSS 预处理器编译、美化、压缩等处理 +- `static` - 静态资源处理任务,可用于图片、字体等静态资源的优化、复制等处理 +- `image` - 图片资源处理任务,专门用于图片资源的压缩、格式转换等处理 +- `server` - 创建本地服务器任务,可以快速创建一个本地开发服务器 - `copy` - 复制文件任务 - `remove` - 删除文件任务 -- `archive` - 打包压缩任务 -- `user` - 用户自定义任务 -- `compose` - 组合任务 +- `archive` - 打包压缩任务,可以将文件打包成 `zip` 压缩包 +- `user` - 用户自定义任务,自定义一些全新任务,完全自主控制处理流程 +- `compose` - 组合任务,将已有任务组合成一个新任务,实现更复杂的构建处理 + +
+ +基于以上核心任务类型,可以通过配置实现自动化的资源处理,比如: + +- HTML/CSS/JS 的语法检查和压缩 +- 图片压缩和格式转换 +- 打包和发布等处理 + +你可以在已有的任务基础上进行扩展,也可以创建全新的任务,还可以将已有任务和新增任务组合成新的构建任务,极大提高工作效率。 -基于以上任务类型,你可以很容易的实现各种构建任务。既可以在已有的任务上扩展,也可以创建新的任务,还可以将已有任务和新增任务组合成新的构建任务。 下面我将详细介绍每一个任务类型,及其使用方法。 diff --git a/docs/help.md b/docs/help.md new file mode 100644 index 0000000..5c21621 --- /dev/null +++ b/docs/help.md @@ -0,0 +1,17 @@ +# 常见问题 + + + +## 1. 安装依赖时间过长 + +1. 设置 `.mpmrc` +```bash +registry=https://registry.npmmirror.com/ +``` + +2. 使用 `cnpm` + + +## 2. 安装依赖失败 +经常碰到安装依赖失败,多数是因为网络原因:很多包将源码托管在 s3 服务器上,国内可能无法访问。 + diff --git a/docs/index.md b/docs/index.md index 9951766..fe97622 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,7 @@ layout: home title: pipflow -titleTemplate: 基于gulp的web开发工作流,内置合并、编译、打包、压缩等功能,极大简化前端开发流程 +titleTemplate: 基于gulp工作流的前端构建工具,内置合并、编译、打包、压缩等功能,极大简化前端开发流程 hero: name: "Pipflow" diff --git a/release.md b/release.md index 118166d..e8bb45a 100644 --- a/release.md +++ b/release.md @@ -1,11 +1,23 @@ -# release +# unit test + +```bash +# 测试某个包 +pnpm test core main + +# 自定义 Jest-cli 选项 +pnpm test -- -p core,main --coverage +``` + +# release + ## 版本发布 1. `pnpm changeset` 2. `pnpm changeset:version` -3. `git push` 后触发 github release,自动发布 +3. 更改`change log`后, `git add & commit` +4. `git push` 后触发 github release,自动发布 ## 语义化版本