You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: packages/gatsby/content/advanced/plugin-tutorial.md
+19-4
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ path: /advanced/plugin-tutorial
4
4
title: "Plugin Tutorial"
5
5
---
6
6
7
-
Starting from the v2, Yarn now supports plugins. For more information about what they are and in which case you'd want to use them, consult the [dedicated page](/features/plugins). We'll talk here about the exact steps needed to write one. It's quite simple, really!
7
+
Starting from the Yarn 2, Yarn now supports plugins. For more information about what they are and in which case you'd want to use them, consult the [dedicated page](/features/plugins). We'll talk here about the exact steps needed to write one. It's quite simple, really!
8
8
9
9
## What does a plugin look like?
10
10
@@ -20,6 +20,17 @@ Open in a text editor a new file called `plugin-hello-world.js`, and type the fo
20
20
module.exports= {
21
21
name:`plugin-hello-world`,
22
22
factory:require=> ({
23
+
// What is this `require` function, you ask? It's a `require`
24
+
// implementation provided by Yarn core that allows you to
25
+
// access various packages (such as @yarnpkg/core) without
26
+
// having to list them in your own dependencies - hence
27
+
// lowering your plugin bundle size, and making sure that
28
+
// you'll use the exact same core modules as the rest of the
29
+
// application.
30
+
//
31
+
// Of course, the regular `require` implementation remains
32
+
// available, so feel free to use the `require` you need for
Copy file name to clipboardExpand all lines: packages/gatsby/content/advanced/questions-and-answers.md
+5-3
Original file line number
Diff line number
Diff line change
@@ -50,6 +50,8 @@ Lockfiles should **always** be kept within the repository. Continuous integratio
50
50
51
51
-`.yarn/unplugged` and `.yarn/build-state.yml` should likely always be ignored since they typically hold machine-specific build artifacts. Ignoring them might however prevent [Zero-Installs](https://next.yarnpkg.com/features/zero-installs) from working (to prevent this, set [`enableScripts`](/configuration/yarnrc#enableScripts) to `false`).
52
52
53
+
-`.yarn/versions` is used by the [version plugin](/features/release-workflow) to store the package release definitions. You will want to keep it within your repository.
54
+
53
55
-`.yarn/cache` and `.pnp.*` may be safely ignored, but you'll need to run `yarn install` to regenerate them between each branch switch - which would be optional otherwise, cf [Zero-Installs](/features/zero-installs).
54
56
55
57
-`yarn.lock` should always be stored within your repository ([even if you develop a library](#should-lockfiles-be-committed-to-the-repository)).
Copy file name to clipboardExpand all lines: packages/gatsby/content/features/plugins.md
+12-27
Original file line number
Diff line number
Diff line change
@@ -8,41 +8,26 @@ Ever since Yarn was created, our very essence has been about experimenting, evol
8
8
9
9
As you can guess, this philosophy (coupled with the high number of external contribution we receive) requires us to iterate fast in order to accomodate with the various experiments that we brew. In a major step forward, Yarn got redesigned in the v2 in order to leverage a new modular API that can be extended through plugins. Nowadays, most of our features are implemented through those plugins - even `yarn add` and `yarn install` are preinstalled plugins!
10
10
11
-
## What can plugins do?
12
-
13
-
-**Plugins can add new resolvers.** Resolvers are the components tasked from converting dependency ranges (for example `^1.2.0`) into fully-qualified package references (for example `npm:1.2.0`). By implementing a resolver, you can tell Yarn which versions are valid candidates to a specific range.
14
-
15
-
-**Plugins can add new fetchers.** Fetchers are the components that take the fully-qualified package references we mentioned in the previous step (for example `npm:1.2.0`) and know how to obtain the data of the package they belong to. Fetchers can work with remote packages (for example the npm registry), but can also find the packages directly from their location on the disk (or any other data source).
16
-
17
-
-**Plugins can add new linkers.** Once all the packages have been located and are ready for installation, Yarn will call the linkers to generate the files needed for the install targets to work properly. As an example, the PnP linker would generate the `.pnp.js` manifest, and a Python linker would instead generate the virtualenv files needed.
18
-
19
-
-**Plugins can add new commands.** Each plugin can ship as many commands as they see fit, which will be injected into our CLI (also making them available through `yarn --help`). Because the Yarn plugins are dynamically linked with the running Yarn process, they can be very small and guaranteed to share the exact same behavior as your package manager (which wouldn't be the case if you were to reimplement the workspace detection, for example).
11
+
## Where to find plugins?
20
12
21
-
-**Plugins can be integrated with each other.** Each plugin has the ability to trigger special actions called hooks, and to register themselves to any defined hook. So for example, you could make a plugin that would execute an action each time a package is added as dependency of one of your workspaces!
22
-
23
-
## How to use plugins?
24
-
25
-
The Yarn plugins are single-file JS scripts. They are easy to use:
13
+
Just type [`yarn plugin list`](/cli/plugin/list), or consult the repository: [plugins.yml](https://github.com/yarnpkg/berry/blob/master/plugins.yml).
26
14
27
-
### Automatic setup
15
+
Note that the plugins exposed through `yarn plugin list` are only the official ones. Since plugins are single-file JS scripts, anyone can author them. By using [`yarn plugin import`](/cli/plugin/import) with an URL or a filesystem path, you'll be able to download (and execute, be careful!) code provided by anyone.
28
16
29
-
The official plugins (the ones whose development happen on the Yarn repository) can be installed using the following commands:
17
+
## How to write plugins?
30
18
31
-
-`yarn plugin list` will print the name of all available [official plugins](https://github.com/yarnpkg/berry/tree/plugins.yml).
19
+
We have a tutorial for this! Head over to [Plugin Tutorial](/advanced/plugin-tutorial).
32
20
33
-
-`yarn plugin import <plugin-name>` will download one of the plugins from the list, store it within the `.yarn/plugins` directory, and modify your local `.yarnrc.yml` file to reference it.
21
+
## What can plugins do?
34
22
35
-
-`yarn plugin import <url>` will do the same thing, but because it uses an URL it will also work with any plugin regardless of where the plugin is actually hosted.
23
+
-**Plugins can add new resolvers.** Resolvers are the components tasked from converting dependency ranges (for example `^1.2.0`) into fully-qualified package references (for example `npm:1.2.0`). By implementing a resolver, you can tell Yarn which versions are valid candidates to a specific range.
36
24
37
-
### Manual setup
25
+
-**Plugins can add new fetchers.** Fetchers are the components that take the fully-qualified package references we mentioned in the previous step (for example `npm:1.2.0`) and know how to obtain the data of the package they belong to. Fetchers can work with remote packages (for example the npm registry), but can also find the packages directly from their location on the disk (or any other data source).
38
26
39
-
The `yarn plugin import` command is useful, but in case you prefer to setup your project yourself:
27
+
-**Plugins can add new linkers.** Once all the packages have been located and are ready for installation, Yarn will call the linkers to generate the files needed for the install targets to work properly. As an example, the PnP linker would generate the `.pnp.js` manifest, and a Python linker would instead generate the virtualenv files needed.
40
28
41
-
-Download the plugin you want to use and put it somewhere
29
+
-**Plugins can add new commands.** Each plugin can ship as many commands as they see fit, which will be injected into our CLI (also making them available through `yarn --help`). Because the Yarn plugins are dynamically linked with the running Yarn process, they can be very small and guaranteed to share the exact same behavior as your package manager (which wouldn't be the case if you were to reimplement the workspace detection, for example).
42
30
43
-
-Update your project-level `.yarnrc.yml` file by adding the following property:
31
+
-**Plugins can register to some events.** Yarn has a concept known as "hooks", where events are periodically triggered during the lifecycle of the package manager. Plugins can register to those hooks in order to add their own logic depending on what the core allows. For example, the `afterAllInstalled` hook will be called each time the `Project#install` method ends - typically after each `yarn install`.
44
32
45
-
```yaml
46
-
plugins:
47
-
- "./my-plugin.js"
48
-
```
33
+
-**Plugins can be integrated with each other.** Each plugin has the ability to trigger special actions called hooks, and to register themselves to any defined hook. So for example, you could make a plugin that would execute an action each time a package is added as dependency of one of your workspaces!
thrownewReportError(MessageName.PLUGIN_NAME_NOT_FOUND,`Couldn't find a plugin named "${key}" on the remote registry. Note that only the plugins referenced on our website (https://github.com/yarnpkg/berry/blob/master/plugins.yml) can be referenced by their name; any other plugin will have to be referenced through its public url (for example https://github.com/yarnpkg/berry/raw/master/packages/plugin-typescript/bin/%40yarnpkg/plugin-typescript.js).`);
66
-
67
-
pluginUrl=data[key].url;
68
-
}else{
65
+
if(this.name.match(/^https?:/)){
69
66
try{
70
67
// @ts-ignore We don't want to add the dom to the TS env just for this line
71
-
newURL(name);
68
+
newURL(this.name);
72
69
}catch{
73
-
thrownewReportError(MessageName.INVALID_PLUGIN_REFERENCE,`Plugin specifier "${name}" is neither a plugin name nor a valid url`);
70
+
thrownewReportError(MessageName.INVALID_PLUGIN_REFERENCE,`Plugin specifier "${this.name}" is neither a plugin name nor a valid url`);
thrownewReportError(MessageName.PLUGIN_NAME_NOT_FOUND,`Couldn't find a plugin named "${identStr}" on the remote registry. Note that only the plugins referenced on our website (https://github.com/yarnpkg/berry/blob/master/plugins.yml) can be referenced by their name; any other plugin will have to be referenced through its public url (for example https://github.com/yarnpkg/berry/raw/master/packages/plugin-typescript/bin/%40yarnpkg/plugin-typescript.js).`);
0 commit comments