Skip to content

Commit 23575bb

Browse files
dhhdhh
authored
Pinning means downloading (#217)
1 parent b372f2e commit 23575bb

File tree

2 files changed

+7
-101
lines changed

2 files changed

+7
-101
lines changed

‎README.md

+3-85
Original file line numberDiff line numberDiff line change
@@ -86,91 +86,12 @@ Note: Sprockets used to serve assets (albeit without filename digests) it couldn
8686

8787
## Using npm packages via JavaScript CDNs
8888

89-
Importmap for Rails is designed to be used with JavaScript CDNs for your npm package dependencies. The CDNs provide pre-compiled distribution versions ready to use, and offer a fast, efficient way of serving them.
89+
Importmap for Rails downloads and vendors your npm package dependencies via JavaScript CDNs that provide pre-compiled distribution versions.
9090

9191
You can use the `./bin/importmap` command that's added as part of the install to pin, unpin, or update npm packages in your import map. This command uses an API from [JSPM.org](https://jspm.org) to resolve your package dependencies efficiently, and then add the pins to your `config/importmap.rb` file. It can resolve these dependencies from JSPM itself, but also from other CDNs, like [unpkg.com](https://unpkg.com) and [jsdelivr.com](https://www.jsdelivr.com).
9292

93-
It works like so:
94-
95-
```bash
96-
./bin/importmap pin react react-dom
97-
Pinning "react" to https://ga.jspm.io/npm:react@17.0.2/index.js
98-
Pinning "react-dom" to https://ga.jspm.io/npm:react-dom@17.0.2/index.js
99-
Pinning "object-assign" to https://ga.jspm.io/npm:object-assign@4.1.1/index.js
100-
Pinning "scheduler" to https://ga.jspm.io/npm:scheduler@0.20.2/index.js
101-
102-
./bin/importmap json
103-
104-
{
105-
"imports": {
106-
"application": "/assets/application-37f365cbecf1fa2810a8303f4b6571676fa1f9c56c248528bc14ddb857531b95.js",
107-
"react": "https://ga.jspm.io/npm:react@17.0.2/index.js",
108-
"react-dom": "https://ga.jspm.io/npm:react-dom@17.0.2/index.js",
109-
"object-assign": "https://ga.jspm.io/npm:object-assign@4.1.1/index.js",
110-
"scheduler": "https://ga.jspm.io/npm:scheduler@0.20.2/index.js"
111-
}
112-
}
113-
```
114-
115-
As you can see, the two packages react and react-dom resolve to a total of four dependencies, when resolved via the jspm default.
116-
117-
Now you can use these in your application.js entrypoint like you would any other module:
118-
119-
```js
120-
import React from "react"
121-
import ReactDOM from "react-dom"
122-
```
123-
124-
You can also designate a specific version to pin:
125-
126-
```bash
127-
./bin/importmap pin react@17.0.1
128-
Pinning "react" to https://ga.jspm.io/npm:react@17.0.1/index.js
129-
Pinning "object-assign" to https://ga.jspm.io/npm:object-assign@4.1.1/index.js
130-
```
131-
132-
Or even remove pins:
133-
134-
```bash
135-
./bin/importmap unpin react
136-
Unpinning "react"
137-
Unpinning "object-assign"
138-
```
139-
140-
If you pin a package that has already been pinned, it'll be updated inline, along with its dependencies.
141-
142-
You can control the environment of the package for packages with separate "production" (the default) and "development" builds:
143-
14493
```bash
145-
./bin/importmap pin react --env development
146-
Pinning "react" to https://ga.jspm.io/npm:react@17.0.2/dev.index.js
147-
Pinning "object-assign" to https://ga.jspm.io/npm:object-assign@4.1.1/index.js
148-
```
149-
150-
You can also pick an alternative, supported CDN provider when pinning, like `unpkg` or `jsdelivr` (`jspm` is the default):
151-
152-
```bash
153-
./bin/importmap pin react --from jsdelivr
154-
Pinning "react" to https://cdn.jsdelivr.net/npm/react@17.0.2/index.js
155-
```
156-
157-
Remember, though, that if you switch a pin from one provider to another, you may have to clean up dependencies added by the first provider that isn't used by the second provider.
158-
159-
Run `./bin/importmap` to see all options.
160-
161-
Note that this command is merely a convenience wrapper to resolving logical package names to CDN URLs. You can also just lookup the CDN URLs yourself, and then pin those. For example, if you wanted to use Skypack for React, you could just add the following to `config/importmap.rb`:
162-
163-
```ruby
164-
pin "react", to: "https://cdn.skypack.dev/react"
165-
```
166-
167-
168-
## Downloading vendor files from the JavaScript CDN
169-
170-
If you don't want to use a JavaScript CDN in production, you can also download vendored files from the CDN when you're setting up your pins:
171-
172-
```bash
173-
./bin/importmap pin react --download
94+
./bin/importmap pin react
17495
Pinning "react" to vendor/react.js via download from https://ga.jspm.io/npm:react@17.0.2/index.js
17596
Pinning "object-assign" to vendor/object-assign.js via download from https://ga.jspm.io/npm:object-assign@4.1.1/index.js
17697
```
@@ -184,17 +105,14 @@ pin "object-assign" # https://ga.jspm.io/npm:object-assign@4.1.1/index.js
184105

185106
The packages are downloaded to `vendor/javascript`, which you can check into your source control, and they'll be available through your application's own asset pipeline serving.
186107

187-
If you later wish to remove a downloaded pin, you again pass `--download`:
108+
If you later wish to remove a downloaded pin:
188109

189110
```bash
190111
./bin/importmap unpin react --download
191112
Unpinning and removing "react"
192113
Unpinning and removing "object-assign"
193114
```
194115

195-
Just like with a normal pin, you can also update a pin by running the `pin --download` command again.
196-
197-
198116
## Preloading pinned modules
199117

200118
To avoid the waterfall effect where the browser has to load one file after another before it can get to the deepest nested import, importmap-rails supports [modulepreload links](https://developers.google.com/web/updates/2017/12/modulepreload). Pinned modules can be preloaded by appending `preload: true` to the pin.

‎lib/importmap/commands.rb

+4-16
Original file line numberDiff line numberDiff line change
@@ -12,18 +12,12 @@ def self.exit_on_failure?
1212
desc "pin [*PACKAGES]", "Pin new packages"
1313
option :env, type: :string, aliases: :e, default: "production"
1414
option :from, type: :string, aliases: :f, default: "jspm"
15-
option :download, type: :boolean, aliases: :d, default: false
1615
def pin(*packages)
1716
if imports = packager.import(*packages, env: options[:env], from: options[:from])
1817
imports.each do |package, url|
19-
if options[:download]
20-
puts %(Pinning "#{package}" to #{packager.vendor_path}/#{package}.js via download from #{url})
21-
packager.download(package, url)
22-
pin = packager.vendored_pin_for(package, url)
23-
else
24-
puts %(Pinning "#{package}" to #{url})
25-
pin = packager.pin_for(package, url)
26-
end
18+
puts %(Pinning "#{package}" to #{packager.vendor_path}/#{package}.js via download from #{url})
19+
packager.download(package, url)
20+
pin = packager.vendored_pin_for(package, url)
2721

2822
if packager.packaged?(package)
2923
gsub_file("config/importmap.rb", /^pin "#{package}".*$/, pin, verbose: false)
@@ -39,17 +33,11 @@ def pin(*packages)
3933
desc "unpin [*PACKAGES]", "Unpin existing packages"
4034
option :env, type: :string, aliases: :e, default: "production"
4135
option :from, type: :string, aliases: :f, default: "jspm"
42-
option :download, type: :boolean, aliases: :d, default: false
4336
def unpin(*packages)
4437
if imports = packager.import(*packages, env: options[:env], from: options[:from])
4538
imports.each do |package, url|
4639
if packager.packaged?(package)
47-
if options[:download]
48-
puts %(Unpinning and removing "#{package}")
49-
else
50-
puts %(Unpinning "#{package}")
51-
end
52-
40+
puts %(Unpinning and removing "#{package}")
5341
packager.remove(package)
5442
end
5543
end

0 commit comments

Comments
 (0)