unplugin-conditional-compilation

A plugin that selectively compiles code based on environmental variables,for Vite & Webpack & Esbuild & Rollup

Install

[npm|pnpm] i unplugin-conditional-definition -D

or

yarn add unplugin-conditional-definition -D

Demo

Example: playground/

// vite.config.ts
import viteConditionalDefinition from 'unplugin-conditional-definition/vite'

export default defineConfig({
  plugins: [
    viteConditionalDefinition({
      /**
       * your enviorment string
       * @type string[]
       */
      env: [],
      // type : 'strict' | 'ignore' | 'transform'
      mode: 'strict',
      // filters for transforming targets
      exclude: [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/, /[\\/]\.svn[\\/]/],
    }),
  ],
})

// rollup.config.js
import rollupConditionalDefinition from 'unplugin-conditional-definition/rollup'

export default {
  plugins: [
    rollupConditionalDefinition({
      /**
       * your enviorment string
       * @type string[]
       */
      env: [],
      // type : 'strict' | 'ignore' | 'transform'
      mode: 'strict',
      // filters for transforming targets
      exclude: [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/, /[\\/]\.svn[\\/]/],
    }),
  ],
}

// webpack.config.js
const webpackConditionalDefinition = require('unplugin-conditional-definition/webpack').default
const ConditionalDefinitionLoader = require('unplugin-conditional-definition/webpack').loader
const { VueLoaderPlugin } = require('vue-loader')

module.exports = {
  /* ... */
  module: {
    rules: [
      /* ... */
      // you must use the loader to transform your vue code
      {
        test: /\.vue$/,
        use: ['vue-loader', ConditionalDefinitionLoader + '.cjs'],
      },
      /* ... */
    ],
  },
  plugins: [
    new VueLoaderPlugin(),
    webpackConditionalDefinition({
      /**
       * your enviorment string
       * @type string[]
       */
      env: [],
    }),
  ],
}

// Not support.
// The esbuild will remove almost all comments in the code.

// rspack.config.js
const RspackPlugin = require('unplugin-conditional-definition/rspack').default
const ConditionalDefinitionLoader = require('unplugin-conditional-definition/webpack').loader
const { VueLoaderPlugin } = require('vue-loader')

module.exports = {
  moudle:{
    rules:{
      /* ... */
      {
        test: /\.vue$/,
        // rspack loader only support cjs files
        use: ['vue-loader', ConditionalDefinitionLoader + '.cjs'],
      },
      /* ... */
    }
  },
  plugins: [
    new VueLoaderPlugin(),
    RspackPlugin({
      /**
       * your enviorment string
       * @type string[]
       */
      env: [],
    }),
  ],
}

// rolldown.config.js
import { defineConfig } from 'rolldown'
import Rolldown from 'unplugin-conditional-definition/rolldown'

export default defineConfig({
  plugins: [
    Rolldown({
      /**
       * your enviorment string
       * @type string[]
       */
      env: [],
    }),
  ],
})

Configuration

The following shows the default values of the configuration

ConditionalDefinition({
  /**
   * your enviorment string
   * @type string[]
   */
  env: [],
  /**
   * This option controls the format of the comments.
   * The `strict` mode will throw an Error if you write comments in the wrong format.
   * The `transform` mode will try to transform your comments to the correct format.
   * The `ignore` mode will ignore the format check.
   * @type 'strict' | 'ignore' | 'transform'
   */
  mode: 'strict',
  /**
   * Whether js compilation is enabled
   * @default true
   */
  js?: boolean
  /**
   * Same as js
   * @default false
   */
  css?: boolean
  /**
   * Same as js
   * Webpack and Rspack does not support. If you want to transform .vue files, you must add loader after the vue-loader
   * @default false
   */
  vue?: boolean
  /**
   * Same as js
   * @default false
   */
  html?: boolean
  // filters for transforming targets
  exclude: [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/, /[\\/]\.svn[\\/]/],
})

Usage

Here suppose the environment variable is LABTOP.

After using the plugin, some specific comments will be used to transform the code. Things to note here:

1. Comments should be written in all uppercase letters, with - concatenation, and multiple variables separated by |. Pay attention to the value of mode, which defaults to strict.

// base usage
// input
// #ifdef MOBILE | SOMETHING-ELSE
console.log('mobile')
// #endif
// #ifndef MOBILE
console.log('not mobile')
// #endif

// output
// #ifdef MOBILE | SOMETHING-ELSE
// #endif
// #ifndef MOBILE
console.log('not mobile')
// #endif

2. Comments must be closed and in the same scope.

// Each of these actions results in an error being thrown.
// #ifndef MOBILE
function test1() {
  // #endif
}
function test2() {
  // #ifndef MOBILE
}
// #endif
function test3() {}
// #endif
// #ifndef MOBILE
function test4() {}

3. Comments of different types should not be shared.

//  will throw err
/* #ifndef MOBILE */
console.log('mobile')
// #endif

4. For vue single-file components, you can't put comments at the top of the scope.

<!-- error -->
<!-- #ifndef MOBILE -->
<template>
  <div>
    <div>mobile</div>
  </div>
</template>
<!-- #endif -->

<!-- corrent -->
<template>
  <div>
    <!-- #ifndef MOBILE -->
    <div>mobile</div>
    <!-- #endif -->
  </div>
</template>

5. Single-line comments are not allowed in css files.

/* error */
.test{
  // #ifndef MOBILE
  color: red;
  // #endif
}
/* corrent */
.test{
  /* #ifndef MOBILE */
  color: red;
  /* #endif */
}

6. Only js and jsx(include ts and tsx) files are checked by default. This is done to improve compilation efficiency.

CHANGELOG

You can see CHANGELOG here.

License

MIT License © 2024-PRESENT lykl