README

运行开发服务器并使用 Webpack 构建您的资源。

安装

将包安装到您的项目中

npm install --save-dev @studiometa/webpack-config

使用方法

在项目根目录创建一个 meta.config.js 文件

// meta.config.mjs
import { defineConfig } from '@studiometa/webpack-config';
import { twig, yaml, tailwindcss, prototyping, eslint, stylelint, hash, https } from '@studiometa/webpack-config/presets';
import { vue } from '@studiometa/webpack-config-preset-vue-3';

export default defineConfig({
  src: [
    './path/to/src/js/*.js',
    './path/to/src/css/*.scss',
  ],
  dist: './path/to/dist',
  public: '/path/to/dist',

  /**
   * Define which target to use when creating the bundle.
   * An array of targets will create a bundle for each target.
   * Defaults to `legacy`.
   *
   * @type {'modern'|'legacy'|Array<'modern'|'legacy'>}
   * @optional
   */
  target: ['modern', 'legacy'],

  /**
   * Analyze the bundle with the WebpackBundleAnalyzer plugin.
   * @type {Boolean}
   * @optional
   */
  analyze: false,

  /**
   * Merge all initial CSS chunks into one file.
   * Use a RegExp or a function to exclude some files:
   * ```js
   * mergeCSS: /^(?!.*css\/do-not-merge\.scss).*$/,
   * mergeCSS(module, chunk) {
   *   return module.constructor.name === 'CssModule';
   * },
   * ```
   * @type {Boolean|RegExp|Function}
   * @optional
   */
  mergeCSS: false,

  /**
   * Extends the Webpack configuration before merging
   * with the environment specific configurations.
   * @type {Function}
   * @optional
   */
  webpack(config, isDev) {},

  /**
   * Extends the development Webpack configuration.
   * @param {WebpackConfig} devConfig The Webpack development config.
   * @type {Function}
   * @optional
   */
  webpackDev(devConfig) {},

  /**
   * Extends the production Webpack configuration.
   * @param {WebpackConfig} devConfig The Webpack production config.
   * @type {Function}
   * @optional
   */
  webpackProd(prodConfig) {},

  /**
   * Configure the `sass-loader` options.
   * @type {Objet}
   * @optional
   * @see https://github.com/webpack-contrib/sass-loader#sassoptions
   */
  sassOptions: {},

  /**
   * Configure the browserSync server if you do not use a proxy by setting
   * this property to `true` or a BrowserSync server configuration object.
   * If the property is a function, it will be used to alter the server
   * configuraton and instance in proxy mode.
   * @see https://browsersync.io/docs/options#option-server
   * @type {Boolean|Object|Function}
   * @optional
   */
  server: true,
  server(bsConfig, bs) {},

  /**
   * Watch for file changes in dev mode and:
   * - reload the browser
   * - or execute a callback
   * @see https://browsersync.io/docs/api#api-watch
   * @type {Array<String|Array>}
   * @optional
   */
  watch: [
    // Watch for changes on all PHP files and reload the browser
    '*.php',
    // Watch for all events on all HTML files and execute the callback
    [
      '*.html',
      (event, file, bs, bsConfig) => {
        if (event === 'change') {
          bs.reload();
        }
      },
    ],
  ],

  /**
   * Use presets to apply pre-made configurations.
   * @type {Array<String|Array<String,Object>>}
   * @optional
   */
  presets: [
    eslint(), // use the `eslint` preset
    stylelint(), // use the `stylelint` preset
    twig(), // use the `twig` preset
    tailwindcss(), // use the `tailwindcss` preset,
    yaml(), // use the `yaml` preset,
    vue(), // use the Vue 3 preset,
    hash(), // use the content hash preset
    https(), // use the https preset
    {
      name: 'my-custom-preset',
      handler(metaConfig, { extendWebpack, extendBrowsersync, isDev }) {
        // ...
      },
    },
  ],
};

配置一个 .env 文件，使用以下变量定义用于代理的应用程序域名

APP_HOST=local.fqdn.com
APP_HOSTNAME=local.fqdn.com
APP_URL=https://local.fqdn.com

然后您可以启动开发服务器

node_modules/.bin/meta dev

或监视更改以构建您的资源

node_modules/.bin/meta watch

并为生产构建您的资源

node_modules/.bin/meta build

您可以使用 --analyze (或 -a) 参数分析您的包：

node_modules/.bin/meta build --analyze

功能

• 使用 ?raw 查询进行原始导入
• 使用 ?as-vue-component 将 SVG 转换为 Vue 组件（需要 vue 预设）

预设

预设可以优雅地扩展 CLI 配置。以下预设包含在包中，无需安装更多依赖项即可使用

• eslint
• stylelint
• twig
• tailwindcss
• yaml
• vue
• hash
• https

请在下面的文档中了解如何使用和配置它们。

可以使用 JS 文件路径（相对于 meta.config.js 文件）使用自定义预设

// meta.config.mjs
import { defineConfig } from '@studiometa/webpack-config';
import myPreset from './my-preset.mjs';

export default defineConfig({
  presets: [
    myPreset({ option: true })
  ],
})

// my-preset.mjs
export default function myPreset(options) {
  return {
    name: 'my-preset',
    async handler(metaConfig, { extendWebpack, isDev }) {
      metaConfig.public = 'auto';
      await extendWebpack(metaConfig, async (webpackConfig) => {
        webpackConfig.optimization.minimize = false;
      });
    }
  }
}

eslint

使用 eslint-webpack-plugin 添加 ESLint 验证。

选项

选项对象直接传递给 ESLintPlugin 构造函数，有关详细信息，请参阅 包文档。

示例

不进行配置使用它

import { defineConfig } from '@studiometa/webpack-config';
import { eslint } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [eslint()],
});

或传递自定义选项

import { defineConfig } from '@studiometa/webpack-config';
import { eslint } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [
    eslint({
      fix: false,
    }),
  ],
});

stylelint

使用 stylelint-webpack-plugin 添加 StyleLint 验证。

选项

选项对象直接传递给 StylelintPlugin 构造函数，有关详细信息，请参阅 包文档。

示例

不进行配置使用它

import { defineConfig } from '@studiometa/webpack-config';
import { stylelint } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [stylelint()],
});

或传递自定义选项

import { defineConfig } from '@studiometa/webpack-config';
import { stylelint } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [
    stylelint({
      fix: false,
    }),
  ],
});

twig

将 twig-html-loader 添加到 Webpack 配置中。

选项

选项对象直接传递给 twig-html-loader。

示例

不进行配置使用它

import { defineConfig } from '@studiometa/webpack-config';
import { twig } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [twig()],
});

或配置加载器选项

import { defineConfig } from '@studiometa/webpack-config';
import { twig } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [
    twig({
      debug: true,
    }),
  ],
});

tailwindcss

将 Tailwind CSS 添加到 PostCSS 配置中，并使用 tailwind-config-viewer 在开发模式下启用 Tailwind 配置预览。

选项

• path (String): Tailwind CSS 入口文件的绝对路径

示例

不进行配置使用它

import { defineConfig } from '@studiometa/webpack-config';
import { tailwindcss } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [tailwindcss()],
});

如果 meta CLI 无法解析 tailwindcss 包，指定其路径

import path from 'node:path';
import { defineConfig } from '@studiometa/webpack-config';
import { twig } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [
    tailwindcss({
      path: path.resolve('./node_modules/tailwindcss/lib/index.js'),
    }),
  ],
});

默认 Tailwind 配置查看器的路由为 /_tailwind/。可以使用 configViewerPath 选项进行自定义

import { defineConfig } from '@studiometa/webpack-config';
import { twig } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [
    tailwindcss({
      configViewerPath: '/__custom_tailwind_viewer_path',
    }),
  ],
});

yaml

使用 js-yaml-loader 添加对 YAML 文件导入的支持。

选项

• loaderOptions (Object): js-yaml-loader 的 选项

示例

import { defineConfig } from '@studiometa/webpack-config';
import { yaml } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [yaml()],
});

vue

支持Vue 2或3。Vue的预设分布在两个不同的包中，因为它们的依赖无法在一个包中安装。您需要安装与您项目使用的版本对应的包。

# For Vue 2
npm install --save-dev @studiometa/webpack-config-preset-vue-2
# Or for Vue 3
npm install --save-dev @studiometa/webpack-config-preset-vue-3

示例

import { defineConfig } from '@studiometa/webpack-config';
import vue from '@studiometa/webpack-config-preset-vue-3';

export default defineConfig({
  presets: [vue()],
});

hash

在生产中将内容哈希添加到文件名中。

选项

此预设没有选项。

示例

import { defineConfig } from '@studiometa/webpack-config';
import { hash } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [hash()],
});

https

使用mkcert为本地开发服务器生成SSL证书。在开发模式下代理到仅支持HTTPS的URL时可能很有用。

选项

此预设没有选项。

示例

import { defineConfig } from '@studiometa/webpack-config';
import { https } from '@studiometa/webpack-config/presets';

export default defineConfig({
  presets: [https()],
});

贡献

该项目使用Git Flow管理分支，每个功能分支必须通过拉取请求合并到develop分支。