Create Tailwind CSS plugin and publish it to npm with ease.
- Tests with Jest (v26)
- ESLint config with
airbnb-base
andprettier
- Format code with Prettier
- Pre-commit hooks with husky
- Run Tests with Github Actions
- Publish to NPM with Github Actions
- Clone a Template/Repository
To get started click Use this template button, or clone the repository:
$ git clone git@github.com:Landish/tailwindcss-plugin-boilerplate.git your-tailwindcss-plugin-name
- Install Dependencies
$ cd your-tailwindcss-plugin-name
$ npm install
- Update
package.json
- Update
name
,description
,author
and other relevant keys to match your plugin needs. - If you want to publish your plugin to npm, remove
private
key frompackage.json
.
- Choose a License
By default this boilerplate uses MIT license. You can change this in package.json
and LICENSE
files to match your needs. If you don't know which license to use, checkout the https://choosealicense.com/.
- Update Source Code
- Replace
YOUR_PLUGIN_NAME
with your plugin name inindex.js
andtest.js
- Customize your plugin options under
YOUR_PLUGIN_NAME
key intheme
object. - Customize your plugin variants under
YOUR_PLUGIN_NAME
key invariants
object.
theme: {
// ...
YOUR_PLUGIN_NAME: {
CUSTOM_OPTION: false,
},
// ...
},
variants: {
// ...
YOUR_PLUGIN_NAME: ['responsive'],
// ...
}
Learn more on writing Tailwind CSS plugins in docs.
- Run Tests
Run npm run test
to test your code. If you run npm run test:watch
command, it will watch for file changes and run tests automatically. If you use Github Actions, this boilerplate will run tests automatically on new commits in main
branch and on pull requests. See .github/workflows/test.yml for more.
- Publish to Github
If you cloned this repository and not used it as a template, you might need to remove .git
directory and reinitialize git again before publishing to your Github account.
$ cd your-tailwindcss-plugin-name
$ rm -rf .git
$ git init
Alternatively you can just change the remote git URL.
# Verify current remote URL
$ git remote -v
> origin git@github.com:Landish/tailwindcss-plugin-boilerplate.git (fetch)
> origin git@github.com:Landish/tailwindcss-plugin-boilerplate.git (push)
# Change remote URL
$ git remote set-url origin git@github.com:USERNAME/REPOSITORY.git
# Verify new remote URL
$ git remote -v
> origin git@github.com:USERNAME/REPOSITORY.git (fetch)
> origin git@github.com:USERNAME/REPOSITORY.git (push)
- Publish to NPM
Tailwind CSS Plugin Boilerplate comes with a Github Action which automatically publishes your plugin to npm, when a new Release is created on your plugin's Github repository.
To setup automatic releases on npm follow the insturctions below:
- Login to npm with your credentials.
- Under Access Tokens page click Generate New Token button.
- On New Access Token page select an option Automation and click Generate Token button.
- Copy that Token and go to Settings tab in your Github Repository.
- In Secrets page click New repository secret button.
- In Name field write
NPM_TOKEN
, in Value field paste that copied Token from npm and click Add Secret button. - Remove
private
key frompackage.json
- Update
version
key inpackage.json
- Create new Release in your Github repository
It will run npm test
before publishing and after couple of minutes your plugin will be available on npm.
If you don't want to publish your plugin to npm, simply remove this file and keep private
key to true
in your package.json
file. You can always remove (unpublish) your published package from npm with npm unpublish your-package-name -f
command.
For more details take a look at the .github/workflows/npm-publish.yml.
- Update Readme
Once you publish your plugin to npm, make you sure you update README.md
with the configuration options and example codes, similar to this:
Install the plugin from npm:
$ npm install your-tailwindcss-plugin-name
Then add the plugin to your tailwind.config.js
file:
// tailwind.config.js
module.exports = {
theme: {
// ...
YOUR_PLUGIN_NAME: {
// ...
},
},
variants: {
// ...
YOUR_PLUGIN_NAME: ['responsive'],
// ...
},
plugins: [
// ...
require('your-tailwindcss-plugin-name'),
// ...
],
};
Tailwind CSS Plugin Boilerplate is licensed under MIT license.