v2.0.0

Author: caoxiemeihao

CHANGELOG.md

@@ -1,3 +1,16 @@
+## 2.0.0 (2023-06-20)
+
+**Break**. This will be a completely new version.
+
+Due to the bundling format of Vite (Rollup), it is not suitable to build a pure js module. It happens that a C/C++ native module can only be a cjs module. So this new version will use Webpack for pre-bundle. It behaves really similar to Vite's own [Dependency Pre-Bundling](https://vitejs.dev/guide/dep-pre-bundling.html#dependency-pre-bundling).
+Thanks to [Erick Zhao](https://github.com/erickzhao) for the inspiration.
+
+- Supports Electron/Node
+- Compatible [Electron Forge](https://github.com/electron/forge) and [
+Electron⚡️Vite](https://github.com/electron-vite)
+
+#### [How to work](https://github.com/vite-plugin/vite-plugin-native/blob/v2.0.0/README.md#how-to-work)
+
 ## 0.2.0 (2023-06-07)
 
 - 8127327 feat: support `node-bindings`

README.md

@@ -1,27 +1,31 @@
 # vite-plugin-native
 
-Plugin for Node native extensions. The project is inspired by the [rollup-plugin-natives](https://github.com/danielgindi/rollup-plugin-natives)
+Supports Node/Electron C/C++ native addons. It is a bundle solution based on [Webpack](https://github.com/webpack/webpack).
+
+> Thanks [Erick Zhao](https://github.com/erickzhao) for providing inspiration :)
 
 [![NPM version](https://img.shields.io/npm/v/vite-plugin-native.svg)](https://npmjs.org/package/vite-plugin-native)
 [![NPM Downloads](https://img.shields.io/npm/dm/vite-plugin-native.svg)](https://npmjs.org/package/vite-plugin-native)
 
-- ✅ [@mapbox/node-pre-gyp](https://github.com/mapbox/node-pre-gyp)
-- ✅ [node-gyp-build](https://github.com/prebuild/node-gyp-build)
-- ✅ Cross-platform cross-compile
+English | [简体中文](./README.zn-CN.md)
+
 ## Install
 
 ```bash
-npm i vite-plugin-native -D
+npm i -D vite-plugin-native
 ```
 
 ## Usage
 
-```javascript
+```js
 import native from 'vite-plugin-native'
 
 export default {
   plugins: [
-    native(/* options */)
+    native({
+      // Enable Webpack
+      webpack: {},
+    })
   ]
 }
 ```
@@ -30,62 +34,21 @@ export default {
 
 ```ts
 export interface NativeOptions {
-  /**
-   * Where we want to physically put the extracted `.node` files
-   * @default 'dist-native'
-   */
-  outDir?: string
-  /**
-   * - Modify the final filename for specific modules
-   * - A function that receives a full path to the original file, and returns a desired filename
-   * - Or a function that returns a desired file name and a specific destination to copy to
-   * @experimental
-   * @todo better calculation value of `id` automatically
-   */
-  map?: (mapping: {
-    /** `.node` file path */
-    native: string
-    /** require id of `.node` file */
-    id: string
-    /** `.node` file output location */
-    output: string
-  }) => typeof mapping
-  /**
-   * - Use `dlopen` instead of `require`/`import`
-   * - This must be set to true if using a different file extension that `.node`
-   */
-  dlopen?: boolean
-  /**
-   * If the target is `esm`, so we can't use `require` (and `.node` is not supported in `import` anyway), we will need to use `createRequire` instead 
-   * @default 'cjs'
-   */
-  target?: 'cjs' | 'esm'
+  /** @default 'node_natives' */
+  assetsDir?: string
+  /** By default native modules are automatically detected if this option is not explicitly configure by the user. */
+  natives?: string[] | ((natives: string[]) => string[])
+  /** Enable and configure webpack. */
+  webpack?: {
+    config?: (config: Configuration) => Configuration | undefined | Promise<Configuration | undefined>
+    'node-loader'?: NodeLoaderOptions,
+    '@vercel/webpack-asset-relocator-loader'?: WebpackAssetRelocatorLoader,
+  },
 }
 ```
 
-## Advanced
+## How to work
 
-Three advanced uses are described in the code comments
+> TODO: Translate into English.
 
-```ts
-import native from 'vite-plugin-native'
-
-export default {
-  plugins: [
-    native({
-      map(mapping) {
-        // 🚨 If you want to cross-compile across platforms, you can change the path to `mapping.native` to do so
-
-        // 🚨 If your `build.outDir` is not `dist`, you may need to dynamically adjust the value of `mapping.id` to fit it
-
-        // 🚨 Avoid named conflict
-        if (mapping.native.includes('serialport')) {
-          mapping.id = mapping.id.replace('node.napi', 'node_serialport.napi')
-          mapping.output = mapping.output.replace('node.napi', 'node_serialport.napi')
-        }
-        return mapping
-      },
-    }),
-  ],
-}
-```
+See 👉🏻 [工作原理 (How to work)](./README.zn-CN.md#工作原理)

README.zn-CN.md

@@ -17,12 +17,15 @@ npm i -D vite-plugin-native
 
 ## Usage
 
-```javascript
+```js
 import native from 'vite-plugin-native'
 
 export default {
   plugins: [
-    native(/* options */)
+    native({
+      // Enable Webpack
+      webpack: {},
+    })
   ]
 }
 ```
@@ -31,36 +34,16 @@ export default {
 
 ```ts
 export interface NativeOptions {
-  /**
-   * Where we want to physically put the extracted `.node` files
-   * @default 'dist-native'
-   */
-  outDir?: string
-  /**
-   * - Modify the final filename for specific modules
-   * - A function that receives a full path to the original file, and returns a desired filename
-   * - Or a function that returns a desired file name and a specific destination to copy to
-   * @experimental
-   * @todo better calculation value of `id` automatically
-   */
-  map?: (mapping: {
-    /** `.node` file path */
-    native: string
-    /** require id of `.node` file */
-    id: string
-    /** `.node` file output location */
-    output: string
-  }) => typeof mapping
-  /**
-   * - Use `dlopen` instead of `require`/`import`
-   * - This must be set to true if using a different file extension that `.node`
-   */
-  dlopen?: boolean
-  /**
-   * If the target is `esm`, so we can't use `require` (and `.node` is not supported in `import` anyway), we will need to use `createRequire` instead 
-   * @default 'cjs'
-   */
-  target?: 'cjs' | 'esm'
+  /** @default 'node_natives' */
+  assetsDir?: string
+  /** By default native modules are automatically detected if this option is not explicitly configure by the user. */
+  natives?: string[] | ((natives: string[]) => string[])
+  /** Enable and configure webpack. */
+  webpack?: {
+    config?: (config: Configuration) => Configuration | undefined | Promise<Configuration | undefined>
+    'node-loader'?: NodeLoaderOptions,
+    '@vercel/webpack-asset-relocator-loader'?: WebpackAssetRelocatorLoader,
+  },
 }
 ```
 
@@ -303,11 +286,7 @@ C/C++ 构建的 .node 文件本质上是一个 cjs 模块，无论怎样它都
 
 ## 为什么是 Webpack
 
-<!--
-首先我们从上面的说明中关于 C/C++ 模块的支持能总结出两个点：
-
-1. 必须是 bundle 方案，并且以 cjs 格式构建
-2. 模块需要被一个模块中心管理，这样才能避免 作用域以及同步/异步 带来的副作用问题
--->
-
 你可能已经意识到 Vite 的 Pre-Bundling 的行为与 Webpack 的行为趋同，为什么我们不直接使用 Pre-Bundling 构建 C/C++ 模块，而且它也是基于 cjs 格式的 bundle 方案。主要是 Webpack 的生态优势，这能让我们少做很多事情且低风险。
+
+## 基于 Vite API 方案
+未来是否会提供一个基于 Vite(Rollup) 自身 API 的方案？暂时没有明确计划。作者目前就职于一个与该插件毫无关系的商业公司，对于此项目的维护仅仅是出于对 Vite/Electron 社区的热爱！