Build a Plugin
The simplest plugin
Quick Start
Boilerplate
Start with a basic TypeScript node package boilerplate. If you've never done that before, we recommend using aqu:
pnpm dlx aqu create simple-plugin
? Pick package manager: pnpm
? Specify package description: ()
? Package author:
? Git repository (only for package.json information):
? Pick license: MIT
? Pick template: typescript
cd simple-plugin
Install @learncard/core
Using your preferred package manager, install @learncard/core
pnpm i @learncard/core
Create the Types
To ease plugin development, it's best to start by defining the interface for your plugin. This can be done quite easily using the Plugin
type:
import { Plugin } from '@learncard/core';
export type MyPluginMethods = {
getFavoriteNumber: () => number;
};
export type MyPluginType = Plugin<'MyPluginName', any, MyPluginMethods>;
The preceding file defines a plugin named MyPluginName
that exposes one method: getFavoriteNumber
Create the Plugin
import { MyPluginType } from './types';
export const MyPlugin: MyPluginType = {
name: 'MyPluginName',
methods: { getFavoriteNumber: () => 4 },
};
Create a Test for Your Plugin
It's important to write tests for your plugins, so others can rely on them π
pnpm i --save-dev jest @types/jest
Then, write your test:
import { initLearnCard } from '@learncard/core';
import { MyPlugin } from '../src/index';
describe('MyPlugin', () => {
it('should return my favorite number', async () => {
const learnCard = await initLearnCard();
const learnCardWithMyPlugin = await learnCard.addPlugin(MyPlugin);
const favoriteNumber = learnCardWithMyPlugin.invoke.getFavoriteNumber();
expect(favoriteNumber).toBe(4);
});
});
If all looks good, you should be able to pnpm test
and successfully pass the test:
That's itβyou've got a simple plugin! π
Now you can add it to a LearnCard object:
const learnCard = await initLearnCard();
const learnCardWithMyPlugin = await learnCard.addPlugin(MyPlugin);
console.log(learnCard.invoke.getFavoriteNumber()); // 4
Publish Your Plugin to NPM
If you don't have anything secret contained in your plugin, you are encouraged to publish it as a package to NPM and share it with the world π.
Let's walk through how to do that together:
Make an npm account
If you haven't yet, follow these short steps to create an npm account. You will need to come up with a username, email, and password!
Create the package boilerplate
As noted in our docs on The Simplest Plugin, if you've never set up a TS/node package before, we greatly recommend using aqu!
yarn dlx aqu create learn-card-example-plugin
? Pick package manager: yarn
? Specify package description: () # Describe your plugin!
? Package author: # Who are you?
? Git repository (only for package.json information):
? Pick license: MIT # See https://choosealicense.com/
? Pick template: typescript
cd learn-card-example-plugin
Create a Github Repo
If you've selected an open source license (such as MIT or ISC), please make a Github Repo containing the code to your plugin! If you've never done this before, we recommend using the Github CLI.
First, create a Github Account, then install and login with the CLI. This is usually done with the following command:
gh auth login
After getting all setup, initialize and create the repo with the following commands:
git init
echo "node_modules/" >> .gitignore
echo "dist/" >> .gitignore
git add .
git commit -m "Initial Commit"
gh repo create
? What would you like to do? Push an existing local repository to GitHub
? Path to local repository .
? Repository name learn-card-example-plugin
? Description Example LearnCard Plugin!
? Visibility Public
β Created repository {REPOSITORY_NAME} on GitHub
? Add a remote? Yes
? What should the new remote be called? origin
β Added remote {REPOSITORY_URL}
? Would you like to push commits from the current branch to "origin"? Yes
β Pushed commits to {REPOSITORY_URL}
After getting a repo up, it's a good idea to add the URL (shown above as {REPOSITORY_URL}
) to the package.json
!
"repository": {
"type": "git",
"url": {REPOSITORY_URL}
},
Release the Package
With everything set up, you may run the release command!
pnpm release
If you didn't use aqu to create your package, you may need to use the publish
command directly:
pnpm publish
Congratulations! π₯³ Your plugin is officially published and others may use it by installing it from npm!
Next Steps
For more info on adding plugins to a LearnCard:
Plugin SystemFor more info on constructing the LearnCard object:
Usage ExamplesLast updated
Was this helpful?