# vite-plugin-externals

> externals plugin for vite

Latest version **0.6.2** (published 2023-01-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install vite-plugin-externals
pnpm add vite-plugin-externals
yarn add vite-plugin-externals
bun add vite-plugin-externals
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.6.2 |
| Published | 2023-01-30 |
| First published | 2021-06-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^14.18.0 \|\| >=16.0.0 |
| Dependencies | 4 |
| Unpacked size | 37.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 179 |
| Author | crcong |
| Maintainers | crcong |
| Keywords | vite-plugin, external, externals |

## Links

- npm: https://www.npmjs.com/package/vite-plugin-externals
- Repository: https://github.com/crcong/vite-plugin-externals
- Issues: https://github.com/crcong/vite-plugin-externals/issues
- npm.io page: https://npm.io/package/vite-plugin-externals

## Dependencies (4)

- [acorn](https://npm.io/package/acorn.md) ^8.4.0
- [fs-extra](https://npm.io/package/fs-extra.md) ^10.0.0
- [magic-string](https://npm.io/package/magic-string.md) ^0.25.7
- [es-module-lexer](https://npm.io/package/es-module-lexer.md) ^0.4.1

## Alternatives

- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads

## Recent versions

- 0.6.2 (latest) — 2023-01-30
- 0.6.1 — 2023-01-30
- 0.6.0 — 2023-01-29
- 0.5.2 — 2023-01-29
- 0.5.1 — 2022-07-16
- 0.5.0 — 2022-05-06
- 0.4.0 — 2022-02-21
- 0.3.4 — 2022-02-06
- 0.3.3 — 2022-01-24
- 0.3.2 — 2021-12-14
- 0.3.1 — 2021-12-09
- 0.3.0 — 2021-09-16
- 0.2.0 — 2021-08-25
- 0.1.7 — 2021-08-20
- 0.1.6 — 2021-08-17
- … 6 more at https://npm.io/package/vite-plugin-externals/versions

## README

# vite-plugin-externals

<p>
  <a href="https://www.npmjs.com/package/vite-plugin-externals" target="_blank">
    <img alt="NPM package" src="https://img.shields.io/npm/v/vite-plugin-externals.svg?style=flat">
  </a>
  <a href="https://www.npmjs.com/package/vite-plugin-externals" target="_blank">
    <img alt="downloads" src="https://img.shields.io/npm/dt/vite-plugin-externals.svg?style=flat">
  </a>
  <a href="https://github.com/vitejs/awesome-vite#helpers" target="_blank">
    <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome">
  </a>
</p>

English | [简体中文](README.zh-CN.md)

use to external resources, like webpack externals, but only use in browser now.

Can be used in `production` mode without other `rollup` configuration.

but it will not take effect by default in `commonjs`, such as `ssr`.

## Usage

```bash
npm i vite-plugin-externals -D
```

Add it to `vite.config.js`

```js
// vite.config.js
import { viteExternalsPlugin } from 'vite-plugin-externals'

export default {
  plugins: [
    viteExternalsPlugin({
      vue: 'Vue',
      react: 'React',
      'react-dom': 'ReactDOM',
      // value support chain, transform to window['React']['lazy']
      lazy: ['React', 'lazy']
    }),
  ]
}
```

**Warning**: If you loaded `production` library in `vite dev mode` , may make `HMR` **fail**.

You can use `disableInServe: true` option to avoid transform in serve mode.

Eg.
```html
<!-- may make HMR fail -->
<script src="./vue.global.prod.js"></script>

<!-- good -->
<script src="./vue.global.js"></script>
```

## How to work

transform source code of js file.

```js
// configuration
viteExternalsPlugin({
  vue: 'Vue',
}),
// source code
import Vue from 'vue'
// transformed
const Vue = window['Vue']

// source code
import { reactive, ref as r } from 'vue'
// transformed
const reactive = window['Vue'].reactive
const r = window['Vue'].ref

// source code
import * as vue from 'vue'
// transformed
const vue = window['Vue']

// source code
export { useState as _useState } from 'react'
// transformed
export const _useState = window['React'].useState
```

**Warning**: please use the plugin after converting to JS code, because the plugin only transform JS code. Eg.

```js
import vue from '@vitejs/plugin-vue'

export default {
  plugins: [
    vue(), // @vitejs/plugin-vue will transform SFC to JS code

    // It should be under @vitejs/plugin-vue
    viteExternalsPlugin({
      vue: 'Vue',
    }),
  ]
}
```

If an error occurs, you can check whether the error is caused by the plugin order.

## Configuration

### disableInServe

disable transform in `serve mode` .

```js
viteExternalsPlugin({
  vue: 'Vue',
}, { disableInServe: true })
```


### enforce

vite plugin ordering. Resolve plugin ordering cause unexpected error. Such as [#21](https://github.com/crcong/vite-plugin-externals/issues/21).

See [https://vitejs.dev/guide/api-plugin.html#plugin-ordering](https://vitejs.dev/guide/api-plugin.html#plugin-ordering).

### filter

The files in `node_modules` are filtered by default, and only transform js/ts/vue/jsx/tsx file.

You can specify the `filter` function. Return `true` will be transform to external.

```js
viteExternalsPlugin({
  vue: 'Vue',
}, {
  filter(code, id, ssr) {
    // your code
    return false
  }
}),
```

### useWindow

set `false`, the `window` prefix will not be added.

**Warning**: If your module name has special characters, such as `/`, set useWindow option `false`, will throw error.

```js
viteExternalsPlugin({
  vue: 'Vue',
}, { useWindow: false }),

// source code
import Vue from 'vue'
// transformed, no `const Vue = window['Vue']`
const Vue = Vue
```

### sourceMapOptions

The configuration item of the code sourcemap after code conversion. The library is `magic-string`.

---
_Source: https://npm.io/package/vite-plugin-externals · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._