vite-plugin-gas-hoist 0.1.1 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ja.md +43 -8
- package/README.md +40 -5
- package/package.json +3 -2
- package/src/index.js +136 -14
package/README.ja.md
CHANGED
|
@@ -5,24 +5,27 @@
|
|
|
5
5
|
|
|
6
6
|
[English](README.md)
|
|
7
7
|
|
|
8
|
-
エントリーポイントの `export`
|
|
8
|
+
エントリーポイントの `export` を、ESM の宣言種別(`function` / `const` / `let` / `var`)を保ったまま、Google Apps Script (GAS) のグローバルスコープに公開する Vite プラグインです。
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## デモ
|
|
11
11
|
|
|
12
12
|
ブラウザ上でコードの編集とビルドを試すことができます。ビルド完了後、`dist/app.js` を開くとプラグインの出力を確認できます。
|
|
13
13
|
|
|
14
14
|
[](https://stackblitz.com/github/hd140283/vite-plugin-gas-hoist/tree/main/example?file=src/app.js)
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## 概要
|
|
17
17
|
|
|
18
|
-
GAS
|
|
18
|
+
GAS 向けに Vite でバンドルするときは、複数モジュールを 1 ファイルにまとめるために IIFE フォーマットを使います。`build.lib.name` に末尾 `_` 付きの変数名(例: `lib_`)を指定すれば、IIFE 全体が GAS のライブラリ可視性ルールで外部から隠れるので、内部実装をライブラリ利用者に見せずに済みます。
|
|
19
|
+
|
|
20
|
+
ただ、これだけだとライブラリとして公開したい関数も、エディタの「実行」ボタンから呼び出したい関数も、まとめて隠れてしまいます。このプラグインは、エントリーポイントから `export` したものだけを IIFE の外側に再宣言して、GAS のグローバルスコープに公開します。
|
|
19
21
|
|
|
20
22
|
```js
|
|
21
23
|
// ビルド前(エントリーポイント)
|
|
22
24
|
export const sayHello = (name) => `Hello, ${name}!`;
|
|
23
25
|
|
|
24
|
-
//
|
|
25
|
-
|
|
26
|
+
// ビルド後
|
|
27
|
+
var lib_ = (function(){ /* バンドルされた sayHello を含む IIFE */ })({});
|
|
28
|
+
const sayHello = (...args) => lib_.sayHello(...args); // プラグインが追加
|
|
26
29
|
```
|
|
27
30
|
|
|
28
31
|
## インストール
|
|
@@ -51,12 +54,44 @@ export default defineConfig({
|
|
|
51
54
|
});
|
|
52
55
|
```
|
|
53
56
|
|
|
54
|
-
`build.lib.name` に指定した変数名(上記例では `lib_
|
|
57
|
+
`build.lib.name` に指定した変数名(上記例では `lib_`)を介して、エクスポートが GAS のグローバルスコープに公開されます。
|
|
58
|
+
|
|
59
|
+
## 対応パターン
|
|
60
|
+
|
|
61
|
+
GAS でグローバルに公開するときの目的は、大きく 2 つに分かれます。
|
|
62
|
+
|
|
63
|
+
- **外部公開**: ライブラリとして使われたとき、利用者から `MyLib.foo()` で呼び出せる
|
|
64
|
+
- **内部公開**: 同じプロジェクト内で、エディタの「実行」ボタンやトリガー設定から呼び出せる
|
|
65
|
+
|
|
66
|
+
ESM の宣言種別(`function` / `const` / `let` / `var`)と右辺の形をそのまま保つことで、この 2 つの公開を組み合わせて表現できます。GAS のライブラリ可視性ルール(`function` / `var` は外部公開、`const` / `let` は非公開)がそのまま反映される挙動です。
|
|
67
|
+
|
|
68
|
+
| ESM 宣言 | 出力 | GAS ライブラリ可視性 |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| `export function foo() {}` | `function foo(...args){return lib_.foo(...args)}` | 公開 |
|
|
71
|
+
| `export const FOO = 42` | `const FOO = lib_.FOO` | 非公開 |
|
|
72
|
+
| `export const foo = (x) => x` | `const foo = (...args) => lib_.foo(...args)` | 非公開(エディタの "実行" ドロップダウンに表示) |
|
|
73
|
+
| `export const foo = function(x){...}` | `const foo = function(...args){return lib_.foo(...args)}` | 非公開(同上) |
|
|
74
|
+
| `export let foo = ...` | `let foo = ...`(右辺は const と同形) | 非公開 |
|
|
75
|
+
| `export var foo = ...` | `var foo = ...`(右辺は const と同形) | 公開 |
|
|
76
|
+
|
|
77
|
+
`export { foo }` や `export { foo as bar }` のような specifier 形式の再エクスポートも、ローカル宣言の種別を引き継ぎます。表に当てはまらないパターン(`export default` や `export class`、宣言種別を判定できない再エクスポートなど)はビルド時に警告を出してスキップします。
|
|
78
|
+
|
|
79
|
+
> 関数式・アロー関数式の右辺をそのままラップ形式で再宣言するのは、GAS のエディタの "実行" ドロップダウンに表示させる(トリガー設定や手動実行を可能にする)ためです。値の右辺をラップしないのは、関数として呼び出されないためエディタに出す必要がなく、純粋な参照のほうが読みやすいからです。
|
|
55
80
|
|
|
56
81
|
## 動作条件
|
|
57
82
|
|
|
58
83
|
- `build.lib.formats` に `'iife'` を含むこと
|
|
59
|
-
-
|
|
84
|
+
- エントリーポイントで何かを `export` していること
|
|
85
|
+
|
|
86
|
+
## 0.1.x からの移行
|
|
87
|
+
|
|
88
|
+
0.1.x までは全ての export を `function name(...){...}` 形式で hoist していましたが、0.2.0 以降は ESM の宣言種別を保つようになりました。
|
|
89
|
+
|
|
90
|
+
- `export function foo()`: 挙動は変わらず(`function foo(...){...}` のまま)
|
|
91
|
+
- `export const foo = (x) => x`: `const foo = (...args) => lib_.foo(...args)` に変更(0.1.x では `function foo(...){...}`)
|
|
92
|
+
- `export const FOO = 42`: `const FOO = lib_.FOO` に変更(0.1.x では `function FOO(...){...}`)
|
|
93
|
+
|
|
94
|
+
GAS のライブラリ可視性ルールに沿って宣言種別を意図的に選んでいる場合(公開したいものは `function` / `var`、非公開にしたいものは `const` / `let`)、その意図がビルド出力に反映されるようになります。
|
|
60
95
|
|
|
61
96
|
## ライセンス
|
|
62
97
|
|
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
|
|
6
6
|
[日本語](README.ja.md)
|
|
7
7
|
|
|
8
|
-
A Vite plugin that hoists entry point `export`s to the global scope for Google Apps Script (GAS).
|
|
8
|
+
A Vite plugin that hoists entry point `export`s to the global scope for Google Apps Script (GAS), preserving the original ESM declaration kind (`function` / `const` / `let` / `var`).
|
|
9
9
|
|
|
10
10
|
## Try it
|
|
11
11
|
|
|
@@ -15,14 +15,17 @@ Edit and build in your browser — no setup required. Once the build finishes, o
|
|
|
15
15
|
|
|
16
16
|
## Why?
|
|
17
17
|
|
|
18
|
-
GAS
|
|
18
|
+
When you bundle code for GAS with Vite, you typically use the `iife` format to combine multiple modules into a single file. Naming the IIFE variable with a trailing underscore (e.g. `lib_` via `build.lib.name`) takes advantage of GAS's library visibility rules to hide the entire bundle from library consumers.
|
|
19
|
+
|
|
20
|
+
The catch: that also hides everything you actually want to expose — both functions called by library consumers and functions you want to run from the GAS editor's "Run" dropdown or triggers. This plugin re-declares each entry-point `export` outside the IIFE, so only what you explicitly export becomes globally visible.
|
|
19
21
|
|
|
20
22
|
```js
|
|
21
23
|
// Before build (entry point)
|
|
22
24
|
export const sayHello = (name) => `Hello, ${name}!`;
|
|
23
25
|
|
|
24
|
-
// After build
|
|
25
|
-
|
|
26
|
+
// After build
|
|
27
|
+
var lib_ = (function(){ /* IIFE bundle containing sayHello */ })({});
|
|
28
|
+
const sayHello = (...args) => lib_.sayHello(...args); // added by the plugin
|
|
26
29
|
```
|
|
27
30
|
|
|
28
31
|
## Install
|
|
@@ -51,13 +54,45 @@ export default defineConfig({
|
|
|
51
54
|
});
|
|
52
55
|
```
|
|
53
56
|
|
|
54
|
-
|
|
57
|
+
Exports are hoisted to the global scope via the variable name specified in `build.lib.name` (e.g. `lib_`).
|
|
58
|
+
|
|
59
|
+
## What gets hoisted
|
|
60
|
+
|
|
61
|
+
Exposing something globally in GAS serves one of two purposes:
|
|
62
|
+
|
|
63
|
+
- **External**: callable by library consumers as `MyLib.foo()`
|
|
64
|
+
- **Internal**: visible inside the same project — selectable in the editor's "Run" dropdown and trigger settings
|
|
65
|
+
|
|
66
|
+
By preserving the original ESM declaration kind (`function` / `const` / `let` / `var`) and the right-hand-side shape, the plugin lets you express both axes naturally. GAS's library visibility rules apply directly: `function` and `var` are externally visible, `const` and `let` are not.
|
|
67
|
+
|
|
68
|
+
| ESM declaration | Output | GAS library visibility |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| `export function foo() {}` | `function foo(...args){return lib_.foo(...args)}` | external |
|
|
71
|
+
| `export const FOO = 42` | `const FOO = lib_.FOO` | internal only |
|
|
72
|
+
| `export const foo = (x) => x` | `const foo = (...args) => lib_.foo(...args)` | internal only (appears in the editor's "Run" dropdown) |
|
|
73
|
+
| `export const foo = function(x){...}` | `const foo = function(...args){return lib_.foo(...args)}` | internal only (same) |
|
|
74
|
+
| `export let foo = ...` | `let foo = ...` (right-hand side as above) | internal only |
|
|
75
|
+
| `export var foo = ...` | `var foo = ...` (right-hand side as above) | external |
|
|
76
|
+
|
|
77
|
+
Specifier-form re-exports like `export { foo }` and `export { foo as bar }` inherit the kind of the local declaration. Patterns not covered above (`export default`, `export class`, re-exports whose kind cannot be determined, etc.) are skipped with a build-time warning.
|
|
78
|
+
|
|
79
|
+
> Function and arrow-function right-hand sides are kept as wrapper forms so the binding shows up in the GAS editor's "Run" dropdown (enabling trigger setup and manual invocation). Plain values are hoisted as direct references — they aren't called as functions, so they don't need to appear in the editor.
|
|
55
80
|
|
|
56
81
|
## Requirements
|
|
57
82
|
|
|
58
83
|
- `build.lib.formats` must include `'iife'`
|
|
59
84
|
- Entry point must have at least one `export`
|
|
60
85
|
|
|
86
|
+
## Migration from 0.1.x
|
|
87
|
+
|
|
88
|
+
In 0.1.x, every export was hoisted as `function name(...){...}`. From 0.2.0 onward, the plugin preserves the original ESM declaration kind:
|
|
89
|
+
|
|
90
|
+
- `export function foo()`: unchanged (still `function foo(...){...}`)
|
|
91
|
+
- `export const foo = (x) => x`: now `const foo = (...args) => lib_.foo(...args)` (was `function foo(...){...}` in 0.1.x)
|
|
92
|
+
- `export const FOO = 42`: now `const FOO = lib_.FOO` (was `function FOO(...){...}` in 0.1.x)
|
|
93
|
+
|
|
94
|
+
If you've been choosing declaration kinds intentionally to align with GAS's library visibility rules (`function` / `var` for external, `const` / `let` for internal), that intent is now reflected in the build output.
|
|
95
|
+
|
|
61
96
|
## License
|
|
62
97
|
|
|
63
98
|
[MIT](LICENSE)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vite-plugin-gas-hoist",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "A Vite plugin that hoists entry point exports to the global scope for Google Apps Script",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"vite-plugin",
|
|
@@ -35,10 +35,11 @@
|
|
|
35
35
|
}
|
|
36
36
|
},
|
|
37
37
|
"peerDependencies": {
|
|
38
|
-
"vite": "^8.0.0"
|
|
38
|
+
"vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
|
|
39
39
|
},
|
|
40
40
|
"devDependencies": {
|
|
41
41
|
"@biomejs/biome": "^2.3.6",
|
|
42
|
+
"acorn": "^8.16.0",
|
|
42
43
|
"vite": "^8.0.3",
|
|
43
44
|
"vitest": "^4.1.4"
|
|
44
45
|
},
|
package/src/index.js
CHANGED
|
@@ -19,10 +19,15 @@
|
|
|
19
19
|
*
|
|
20
20
|
* @returns {import('vite').Plugin}
|
|
21
21
|
*/
|
|
22
|
+
/** @typedef {'function' | 'const' | 'let' | 'var'} ExportKind */
|
|
23
|
+
/** @typedef {{ kind: ExportKind, isFn: boolean, isArrow: boolean }} ExportInfo */
|
|
22
24
|
export const vitePluginGasHoist = () => {
|
|
23
25
|
/** @type {string} IIFE variable name from build.lib.name */
|
|
24
26
|
let varName;
|
|
25
27
|
|
|
28
|
+
/** @type {Map<string, ExportInfo>} */
|
|
29
|
+
const exportKinds = new Map();
|
|
30
|
+
|
|
26
31
|
return {
|
|
27
32
|
name: 'vite-plugin-gas-hoist',
|
|
28
33
|
apply: 'build',
|
|
@@ -32,15 +37,76 @@ export const vitePluginGasHoist = () => {
|
|
|
32
37
|
varName = config.build.lib?.name;
|
|
33
38
|
},
|
|
34
39
|
|
|
40
|
+
buildStart() {
|
|
41
|
+
exportKinds.clear();
|
|
42
|
+
},
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Records the declaration kind of each top-level named export so that
|
|
46
|
+
* renderChunk can emit a binding that preserves the original visibility.
|
|
47
|
+
*
|
|
48
|
+
* @param {string} code
|
|
49
|
+
* @param {string} _id
|
|
50
|
+
*/
|
|
51
|
+
transform(code, _id) {
|
|
52
|
+
// Cheap pre-filter: skip modules that obviously have no exports (node_modules, virtual modules, CSS-as-JS, etc.) before paying acorn's cost.
|
|
53
|
+
if (!code.includes('export')) return null;
|
|
54
|
+
|
|
55
|
+
let ast;
|
|
56
|
+
try {
|
|
57
|
+
ast = this.parse(code);
|
|
58
|
+
} catch {
|
|
59
|
+
// Parse errors are surfaced by Vite/Rollup elsewhere; staying silent here avoids double-reporting.
|
|
60
|
+
return null;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** @type {Map<string, ExportInfo>} */
|
|
64
|
+
const localKinds = new Map();
|
|
65
|
+
for (const node of ast.body) {
|
|
66
|
+
if (node.type === 'FunctionDeclaration' && node.id) {
|
|
67
|
+
localKinds.set(node.id.name, { kind: 'function', isFn: true, isArrow: false });
|
|
68
|
+
} else if (node.type === 'VariableDeclaration') {
|
|
69
|
+
for (const decl of node.declarations) {
|
|
70
|
+
if (decl.id.type === 'Identifier') {
|
|
71
|
+
localKinds.set(decl.id.name, classifyVariable(node.kind, decl.init));
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
for (const node of ast.body) {
|
|
78
|
+
if (node.type !== 'ExportNamedDeclaration') continue;
|
|
79
|
+
|
|
80
|
+
if (node.declaration?.type === 'VariableDeclaration') {
|
|
81
|
+
const kind = node.declaration.kind;
|
|
82
|
+
for (const decl of node.declaration.declarations) {
|
|
83
|
+
if (decl.id.type === 'Identifier') {
|
|
84
|
+
exportKinds.set(decl.id.name, classifyVariable(kind, decl.init));
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
} else if (node.declaration?.type === 'FunctionDeclaration') {
|
|
88
|
+
if (node.declaration.id?.type === 'Identifier') {
|
|
89
|
+
exportKinds.set(node.declaration.id.name, { kind: 'function', isFn: true, isArrow: false });
|
|
90
|
+
}
|
|
91
|
+
} else if (node.specifiers.length > 0 && !node.source) {
|
|
92
|
+
for (const spec of node.specifiers) {
|
|
93
|
+
if (spec.type !== 'ExportSpecifier') continue;
|
|
94
|
+
const info = localKinds.get(spec.local.name);
|
|
95
|
+
if (info) {
|
|
96
|
+
exportKinds.set(spec.exported.name, info);
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
return null;
|
|
102
|
+
},
|
|
103
|
+
|
|
35
104
|
renderChunk: {
|
|
36
105
|
order: 'post',
|
|
37
106
|
/**
|
|
38
|
-
* Appends global
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
* ```js
|
|
42
|
-
* function sayHello(...args){return lib_.sayHello(...args)}
|
|
43
|
-
* ```
|
|
107
|
+
* Appends kind-appropriate global hoist bindings for each entry export,
|
|
108
|
+
* skipping unsupported patterns (e.g. `export default`, `export class`,
|
|
109
|
+
* re-exports) whose declaration kind was not recorded by `transform`.
|
|
44
110
|
*
|
|
45
111
|
* @param {string} code
|
|
46
112
|
* @param {import('rollup').RenderedChunk} chunk
|
|
@@ -49,19 +115,75 @@ export const vitePluginGasHoist = () => {
|
|
|
49
115
|
handler(code, chunk, options) {
|
|
50
116
|
if (options.format !== 'iife' || !chunk.isEntry) return null;
|
|
51
117
|
|
|
52
|
-
|
|
53
|
-
|
|
118
|
+
/** @type {Array<{ name: string, info: ExportInfo }>} */
|
|
119
|
+
const known = [];
|
|
120
|
+
/** @type {string[]} */
|
|
121
|
+
const skipped = [];
|
|
122
|
+
|
|
123
|
+
for (const name of chunk.exports) {
|
|
124
|
+
const info = exportKinds.get(name);
|
|
125
|
+
if (info) {
|
|
126
|
+
known.push({ name, info });
|
|
127
|
+
} else {
|
|
128
|
+
skipped.push(name);
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
if (known.length > 0) {
|
|
133
|
+
const label = known.length === 1 ? 'export' : 'exports';
|
|
134
|
+
const list = known.map(({ name, info }) => ` - ${name} (${info.kind})`).join('\n');
|
|
135
|
+
console.log(`[vite-plugin-gas-hoist] Hoisted ${known.length} ${label} to global scope:\n${list}`);
|
|
136
|
+
}
|
|
54
137
|
|
|
55
|
-
|
|
56
|
-
.
|
|
57
|
-
.join('\n');
|
|
138
|
+
if (skipped.length > 0) {
|
|
139
|
+
const label = skipped.length === 1 ? 'export' : 'exports';
|
|
140
|
+
const list = skipped.map((name) => ` - ${name}`).join('\n');
|
|
141
|
+
this.warn(`Skipped ${skipped.length} ${label} (unsupported pattern):\n${list}`);
|
|
142
|
+
}
|
|
58
143
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
144
|
+
if (known.length === 0) return null;
|
|
145
|
+
|
|
146
|
+
const wrappers = known.map(({ name, info }) => emitWrapper(name, info, varName)).join('\n');
|
|
62
147
|
|
|
63
148
|
return `${code}\n${wrappers}\n`;
|
|
64
149
|
},
|
|
65
150
|
},
|
|
66
151
|
};
|
|
67
152
|
};
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Classifies a `VariableDeclaration` declarator as a value or function expression.
|
|
156
|
+
*
|
|
157
|
+
* @param {ExportKind} kind
|
|
158
|
+
* @param {import('estree').Expression | null | undefined} init
|
|
159
|
+
* @returns {ExportInfo}
|
|
160
|
+
*/
|
|
161
|
+
const classifyVariable = (kind, init) => {
|
|
162
|
+
const isArrow = init?.type === 'ArrowFunctionExpression';
|
|
163
|
+
const isFn = isArrow || init?.type === 'FunctionExpression';
|
|
164
|
+
return { kind, isFn, isArrow };
|
|
165
|
+
};
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Renders the hoisted binding for a single export, preserving the original
|
|
169
|
+
* declaration kind and (for `const`/`let` function expressions) the function
|
|
170
|
+
* shape (arrow vs `function` expression) so callers see a callable wrapper
|
|
171
|
+
* that GAS recognizes as a function.
|
|
172
|
+
*
|
|
173
|
+
* @param {string} name
|
|
174
|
+
* @param {ExportInfo} info
|
|
175
|
+
* @param {string} varName
|
|
176
|
+
* @returns {string}
|
|
177
|
+
*/
|
|
178
|
+
const emitWrapper = (name, info, varName) => {
|
|
179
|
+
if (info.kind === 'function') {
|
|
180
|
+
return `function ${name}(...args){return ${varName}.${name}(...args)}`;
|
|
181
|
+
}
|
|
182
|
+
if (info.isFn) {
|
|
183
|
+
if (info.isArrow) {
|
|
184
|
+
return `${info.kind} ${name} = (...args) => ${varName}.${name}(...args)`;
|
|
185
|
+
}
|
|
186
|
+
return `${info.kind} ${name} = function(...args){return ${varName}.${name}(...args)}`;
|
|
187
|
+
}
|
|
188
|
+
return `${info.kind} ${name} = ${varName}.${name}`;
|
|
189
|
+
};
|