swup / plugin

Base class for creating swup plugins 📁

Swup Base Plugin

Base class for creating swup plugins.

Creating a Plugin

To create a new plugin, use the official swup plugin template. It comes with detailed instructions and the required tooling.

Usage

Import the base class and extend your plugin from it.

import Plugin from '@swup/plugin';

export default class PluginName extends Plugin {
  name = 'PluginName';
  mount() {}
  unmount() {}
}

Development

The official swup command-line interface has commands to help with bundling and linting plugins.

npm install --save-dev @swup/cli

Bundling

Bundle the plugin for production using microbundle, creating ESM and UMD builds.

# Bundle and transpile plugin code for distribution
swup package:bundle

# Bundle plugin code in watch mode
swup package:dev

Linting & formatting

Lint the plugin code using prettier and swup's recommended rules.

# Lint plugin code
swup package:lint

# Fix and format any lint errors
swup package:format

Package info

Check that the plugin's package.json file contains the required information for microbundle: input, output, export map, amd name, etc.

# Check plugin package info
swup package:check

plugin's Issues

Extract build CLI from base plugin to avoid bundling build dependencies

I recently got snagged including all of TypeScript as part of a front-end package because @swup/plugin has microbundle as a dependency. It looks like microbundle is used for building assets, rather than as a internal dependency used within src/. So, I think its safe to switch it over :)

Bundling error doesn't abort `npm publish`

Description of the issue

• The npm publish action of plugins won't abort when there are TS compilation errors
• Seems like exit codes aren't handed through properly by the plugin CLI

How to reproduce the issue

• See this recent publish action of preload plugin

`swup-plugin lint` only lints `js` files

Description of the issue

swup-plugin lint should also lint .ts, .mjs, .cjs files.

How to reproduce the issue

Run swup-plugin lint in a Plugin built in TypeScript

Add a way of requiring a minimum swup version

• Optionally let plugins define which version of swup they need to run
• Mostly useful for the v3 switch since there's a few incompatibilities
• Alternative: Stick with feature detection like if (typeof swup.someFunction === 'function') { }