On this page

Authoring powerups

This page will guide you through the process of creating your first powerup

1. Creating your first powerup

The first step is to create the powerup package. This is done using the pup author create command:

bash
pup author create hello-world --description="Creates a hello world script" \
	--variables=name \
	--type=single-use

This creates ~/.powerups/installed/_internal/hello-world/ with the following files:

~/.powerups/installed/_internal/hello-world/
├── .gitignore
├── package.json
├── tsconfig.json
├── index.ts
└── scripts
  └── create-github-repo.sh

A. Setup the package.json

Your package.json is setup automatically.

By default, the main instructions file is mapped to index.ts, you can change it to another file if you prefer.

package.json
{
	"name": "hello-world",
	// ...
	"powerup": {
		"instructions": "index.ts" // <-- Here
	}
}

B. Add a step to the instructions file

index.ts
1import { defineInstructions, type Instructions } from "@liolocs/powerups-sdk";
2
3const instructions: Instructions = {
4	name: "hello-world",
5	type: "single-use",
6	description: "Creates a hello world script",
7	variables: {
8		required: ["name"],
9		optional: [],
10	},
11	intent: [
12		"create a hello world script",
13	],
14	steps: [
15		{
16			type: "dynamic-create",
17			name: "hello-world.ts",
18			template: "src/dynamic-create/hello-world.ts",
19			outputPath: "hello-world.ts",
20		},
21	],
22};
23
24export default defineInstructions(instructions, import.meta.url); // <-- Required

C. Create the template

Create the template your create step is referring to at src/dynamic-create/hello-world.ts.

src/dynamic-create/hello-world.ts
export default function(variables: Record<string, string>): string {
	const { name } = variables;
	return `console.log("Hello ${name}!");`;
}

2. Preview the powerup

You can test your powerup before publishing or building it with the preview command:

bash
pup author preview

You can pass preview flags to the command to control the output:

bash
pup author preview --variables=name --exec="npm run dev"

You can also use a preview.json file instead of passing flags:

preview.json
{
"variables": {
  "name": "world"
},
"exec": "npm run dev"
}

3. Build the powerup

You must build the powerup before it can be used with the command:

bash
pup author build

This will run a verification on the instructions file and create a dist folder containing the necessary files for the powerup to be used.

Your output should look like this:

bash
✓ Built powerup: hello-world
output: /Users/<user>/.powerups/installed/_internal/hello-world/dist

4. Use powerup

Once the powerup is built you can use it locally anywhere by running the following command:

bash
pup use hello-world --name=world --target-dir=./test-hello-world

This will result in the following output:

bash
Created: hello-world.ts

✓ Powerup hello-world was successfully used in /Users/<user>/<path>/test-hello-world

5. Share the powerup

Once the powerup is built you can share by publishing it to npm or git.

Publishing to npm

To publish the powerup to npm run:

bash
npm publish

You may use the conventional commits script to generate a changelog with npm run release.

Users will then be able to install the powerup by running:

bash
pup install npm:<your-user-scope>/hello-world

Publishing to git

To publish the powerup to git simply push the package to a git repo.

You may run the following script to create a github repo using the gh cli and push the package to it.

bash
./scripts/create-github-repo.sh

Users will then be able to install the powerup by running:

bash
pup install git:github.com/<owner>/hello-world
QuickstartCreate a powerup from an existing repo