Skip to content

Commit fbc661a

Browse files
fuweichinfuweichin
committed
update doc
1 parent cfc0d2e commit fbc661a

File tree

2 files changed

+253
-52
lines changed

2 files changed

+253
-52
lines changed

‎CHANGELOG.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Changlog
2+
3+
All notable changes to [rollup-plugin-import-maps](https://www.npmjs.com/package/rollup-plugin-import-maps) will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6+
7+
8+
9+
## [0.2.0] - 2020-06-07
10+
11+
### Added
12+
13+
+ `options.srcText` to use text as importmap source
14+
+ `options.transformingReport` to save transforming report as a file
15+
+ `options.noTransforming` to only mark specifiers defined in importmap as external without transforming
16+
+ `options.exclude` to skip specifiers from resoving
17+
18+
### Changed
19+
20+
+ dropped use of `Buffer` as `options.srcObject`
21+
22+
23+
24+
## [0.1.1] - 2022-06-04
25+
26+
### Fixed
27+
28+
+ fixed resolving of protocol-relative target specifier like `//example.com/foo.js`
29+
30+
### Deprecated
31+
32+
+ use `Buffer` as `options.srcObject` is deprected
33+
34+
35+
36+
## [0.1.0] - 2022-06-02
37+
38+
### Added
39+
40+
+ speicifer transforming of import statement, export statement and dynamic import

‎README.md

Lines changed: 213 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,25 @@
11
# rollup-plugin-import-maps
22

3-
A plugin to resolve ECMAScript module bare import specifiers at build-time for browsers which don't support import-maps, mostly based on **WICG's [import-maps reference implementation](https://github.com/WICG/import-maps/tree/master/reference-implementation)**.
3+
A plugin to resolve ECMAScript module bare/url import specifiers at build-time for browsers which don't support import-maps, mostly based on **WICG's [import-maps reference implementation](https://github.com/WICG/import-maps/tree/master/reference-implementation)**.
4+
5+
**Contents:**
6+
7+
<!--ts-->
8+
9+
* [Install](#install)
10+
* [Usage](#usage)
11+
* [Basic Usage](#basic-usage)
12+
* [Plugin Options](#plugin-options)
13+
* [Caveats](#caveats)
14+
* [Use Cases](#use-cases)
15+
* [Bare Specifiers Transforming](#bare-specifiers-transforming)
16+
* [URL Specifiers Transforming](#url-specifiers-transforming)
17+
* [As a Transitional Polyfill](#as-a-transitional-polyfill)
18+
* [Related Efforts](#related-efforts)
19+
* [Maintainers](#maintainers)
20+
* [License](#license)
21+
<!--te-->
22+
423

524

625
## Install
@@ -9,108 +28,249 @@ A plugin to resolve ECMAScript module bare import specifiers at build-time for b
928
npm install --save-dev rollup-plugin-import-maps
1029
```
1130

31+
32+
1233
## Usage
1334

14-
1. edit rollup.config.js, import and use the plugin
35+
### Basic Usage
36+
37+
edit rollup.config.js, import and use the plugin
1538

1639
```js
1740
import { importMapsPlugin } from 'rollup-plugin-import-maps';
18-
import { readFileSync } from 'fs';
41+
// import { readFileSync } from 'fs';
1942

2043
export default {
2144
input: './src/index.js',
2245
plugins: [
2346
importMapsPlugin({
24-
srcObject: process.env.ROLLUP_WATCH ? readFileSync('./index-dev.importmap') : readFileSync('./index-cdn.importmap')
25-
})
47+
srcPath: './index.importmap',
48+
// srcText: readFileSync('./index.importmap', { encoding: 'utf8' }),
49+
// srcObject: JSON.parse(readFileSync('./index.importmap', { encoding: 'utf8' })),
50+
}),
2651
],
27-
output: {
28-
file: './dist/index.js',
29-
format: 'es'
30-
}
52+
output: [
53+
{
54+
file: './dist/index.js',
55+
format: 'es'
56+
}
57+
]
3158
};
3259
```
3360

34-
2. install some esm-ready packages, for example:
3561

36-
```sh
37-
npm install vue@2.x underscore@1.x
38-
```
3962

40-
3. create importmap files like index-dev.importmap
63+
### Plugin Options
4164

42-
```json
65+
+ `srcPath`:string optional
66+
67+
file path to importmap
68+
69+
+ `srcText`:string optional
70+
71+
plain text of importmap
72+
73+
+ `srcObject`:Object optional
74+
75+
parsed object of importmap
76+
77+
**Note:** One of `srcObject`, `srcText`, `srcPath` should be specified, if multiple of them specified, then precedence order is: srcObject, srcText, srcPath.
78+
79+
+ `baseDir`: string default `process.cwd()`
80+
81+
baseDir to calculate scope paths in order to match scopes defined in importmap
82+
83+
+ `transformingReport`:string default `undefined`
84+
85+
set a file path to save transforming report as a JSON file, will output to Console if value set to `"-"`
86+
87+
+ `noTransform`:boolean default `false`
88+
89+
if value set to `true`, then the plugin will mark specifiers defined in importmap as external, and won't transform those specifiers. useful if you want to build for browsers which already support import-maps and "set external list" with importmap.
90+
91+
+ `exclude`:string|RegExp|Function default `undefined`
92+
93+
skip bare/url specifiers from resolving / transforming according to importmap.
94+
95+
e.g. `/\.(json|wasm|css)$/`, `(source, importer)=> /\.(json|wasm|css)$/.test(source)`, `.css,.wasm,.json`
96+
97+
98+
99+
### Caveats
100+
101+
+ This plugin doesn't yet support transform of module specifiers defined in data url. example data url:
102+
```js
103+
import {foo, bar} from "data:application/javascript;charset=utf-8,import%20%7Bdefault%20as%20foo%7D%20from%20'foo'%3B%0Aexport%20%7Bfoo%7D%3B%0Aexport%20%7Bdefault%20as%20bar%7D%20from%20'bar'%3B";
104+
```
105+
106+
which can be decoded as
107+
108+
```js
109+
import {default as foo} from 'foo';
110+
export {foo};
111+
export {default as bar} from 'bar';
112+
```
113+
114+
+ When tansforming specifiers in [dynamic imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#dynamic_imports), only string literal can be transformed. examples code:
115+
116+
```js
117+
import('foo/locales/en/messages.js') // Yes
118+
import("foo/locales/en/messages.js") // Yes
119+
120+
let lang = 'en';
121+
import('foo/locales/'+lang+'/messages.js') // No
122+
123+
let modulePath = 'foo/locales/en/messages.js'
124+
import(modulePath) // No
125+
126+
import(`foo/locales/en/messages.js`) // No
127+
```
128+
129+
130+
131+
### Use Cases
132+
133+
#### Bare Specifiers Transforming
134+
135+
importmap
136+
137+
```json5
43138
{
44139
"imports": {
45-
"vue": "/node_modules/vue/dist/vue.esm.browser.min.js",
46-
"underscore/": "/node_modules/underscore/",
47-
"@/polyfills/": "/lib/polyfills/"
140+
"three": "/node_modules/three/build/three.module.js",
141+
"three/": "/node_modules/three/",
142+
"underscore": "data:application/javascript;charset=utf-8,export%20default%20window._%3B",
143+
"~/": "//mysite.com/packages/myapp/"
48144
}
49145
}
50146
```
51147

52-
and index-cdn.importmap
148+
input code
149+
150+
```js
151+
import * as THREE from 'three';
152+
import GLTFLoader from 'three/examples/jsm/loaders/GLTFLoader.js';
153+
import underscore from 'underscore';
154+
import '~/polyfills/navigator.userAgentData.js';
155+
// ...
156+
```
157+
158+
output code
159+
160+
```js
161+
import Vue from "/node_modules/vue/dist/vue.esm.browser.min.js";
162+
import jQuery from "data:application/javascript;charset=utf-8,export%20default%20window.jQuery%3B";
163+
import shuffle from "/node_modules/underscore/modules/shuffle.js";
164+
import "//libs.yourcompany.com/polyfills/latest/navigator.userAgentData.js";
165+
// ...
166+
```
167+
168+
#### URL Specifiers Transforming
169+
170+
importmap
53171

54172
```json
55173
{
56174
"imports": {
57-
"vue": "https://unpkg.com/vue@2.x/dist/vue.esm.browser.min.js",
58-
"underscore/": "https://unpkg.com/underscore@1.x/",
59-
"@/polyfills/": "/lib/polyfills/"
175+
"https://unpkg.com/three@0.141.0/build/three.module.js": "/node_modules/three/build/three.module.js",
176+
"node-modules:/": "/node_modules/",
177+
"data:application/javascript;charset=utf-8,export%20default%20window._%3B": "/underscore/underscore-esm-min.js",
178+
"app-home:/": "//mysite.com/packages/myapp/"
60179
}
61180
}
62181
```
63182

64-
4. input code './src/index.js'
183+
input code
65184

66185
```js
67-
import Vue from 'vue';
68-
import shuffle from 'underscore/modules/shuffle.js';
69-
import '@/polyfills/navigator.userAgentData.js';
186+
import * as THREE from 'https://unpkg.com/three@0.141.0/build/three.module.js';
187+
import GLTFLoader from 'node-modules:/three/examples/jsm/loaders/GLTFLoader.js';
188+
import underscore from 'data:application/javascript;charset=utf-8,export%20default%20window._%3B';
189+
import 'app-home:/polyfills/navigator.userAgentData.js';
70190
// ...
71191
```
72192

73-
5. use rollup to watch or build
74-
75-
```sh
76-
rollup -c rollup.config.js -w
77-
# or
78-
rollup -c rollup.config.js
79-
```
80-
81-
6. output code './dist/index.js'
193+
output code
82194

83195
```js
84-
import Vue from '/node_modules/vue/dist/vue.esm.browser.min.js';
85-
import shuffle from '/node_modules/underscore/modules/shuffle.js';
86-
import '/lib/polyfills/navigator.userAgentData.js';
196+
import * as THREE from '/node_modules/three/build/three.module.js';
197+
import GLTFLoader from '/node_modules/three/examples/jsm/loaders/GLTFLoader.js';
198+
import underscore from '/underscore/underscore-esm-min.js';
199+
import '//mysite.com/packages/myapp/polyfills/navigator.userAgentData.js';
87200
// ...
88201
```
89202

90-
or
203+
#### As a Transitional Polyfill
204+
205+
This plugin plays a role of polyfill for browsers but is used at build-time rather than at run-time. If some day (maybe in 2023) all major browsers support import-maps then this plugin can be retired.
206+
207+
You may use rollup to build two distributions, for browsers with or without import-maps support, and load corresponding distribution conditionally. e.g.
91208

92209
```js
93-
import Vue from 'https://unpkg.com/vue@2.x/dist/vue.esm.browser.min.js';
94-
import shuffle from 'https://unpkg.com/underscore@1.x/modules/shuffle.js';
95-
import '/lib/polyfills/navigator.userAgentData.js';
96-
// ...
210+
// rollup.config.js
211+
export default [
212+
{
213+
input: './src/index.js',
214+
plugins: [
215+
importMapsPlugin({
216+
srcPath: './index.importmap',
217+
transformingReport: '-',
218+
}),
219+
],
220+
output: [
221+
{
222+
file: './dist/index.js',
223+
format: 'es'
224+
}
225+
]
226+
},
227+
{
228+
input: './src/index.js',
229+
plugins: [
230+
importMapsPlugin({
231+
srcPath: './index.importmap',
232+
noTransforming: true,
233+
}),
234+
],
235+
output: [
236+
{
237+
file: './dist/index-experimental.js',
238+
format: 'es'
239+
}
240+
]
241+
}
242+
];
97243
```
98244

99-
### Plugin Options
245+
```html
246+
<script type="importmap">
247+
put content of ./index.importmap here
248+
</script>
249+
250+
<script type="module">
251+
if (HTMLScriptElement.supports && HTMLScriptElement.supports('importmap')) {
252+
console.log('Your browser supports import maps.');
253+
import('/dist/index-experimental.js');
254+
}else{
255+
console.log('Your browser doesn\'t support import maps.');
256+
import('/dist/index.js');
257+
}
258+
</script>
259+
```
100260

101-
+ `srcPath`:string optional
102261

103-
file path to importmap
104262

105-
+ `srcObject`:Buffer|ArrayBuffer|Object optional
263+
## Related Efforts
106264

107-
raw buffer of importmap
108-
109-
+ `baseDir`: string default `process.cwd()`
265+
+ [import-maps](#) - Reference implementation playground for import maps proposal
266+
267+
268+
269+
## Maintainers
270+
271+
[@fuweichin](https://github.com/fuweichin)
110272

111-
baseDir to calculate scope paths in order to match scopes defined in importmap
112273

113-
**Note:** either srcPath or srcObject should be specified
114274

115275

116276
## License
@@ -120,3 +280,4 @@ import '/lib/polyfills/navigator.userAgentData.js';
120280
Other licenses of dependencies
121281

122282
+ import-maps: [W3C Software and Document License](http://www.w3.org/Consortium/Legal/2015/copyright-software-and-document) and [W3C CLA](https://www.w3.org/community/about/agreements/cla/)
283+

0 commit comments

Comments
 (0)