Authoring powerups

1. Create the powerup

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

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

This creates:

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

A. Setup the package.json

By default the instructions file is mapped to index.ts, this is done in the package.json’s powerup/instructions property.

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

B. Modify the instructions file

import { defineInstructions, type Instructions } from "@liolocs/powerups-sdk";

const instructions: Instructions = {
  name: "hello-world",
  type: "single-use",
  description: "Creates a hello world script",
  variables: {
    required: ["name"],
    optional: [],
  },
  intent: [
    "create a hello world script",
  ],
  steps: [
    {
      type: "create",
      name: "hello-world.ts",
      template: "templates/hello-world.ts",
      outputPath: "hello-world.ts",
    },
  ],
};

export default defineInstructions(instructions, import.meta.url); // <-- Required

The defined steps in the file are executed when running pup use.

E.G. Running the command

pup use hello-world --name="world"

This will create a file called hello-world.ts in the root of the folder it is run from.

C. Create the template

The template is the file that will be used to create the instructions file. It is a file that is rendered by the cli.

templates/hello-world.ts

export default function(variables: Record<string, string>): string {
  const { name } = variables;
  return `console.log("Hello ${name}!");`;
}

2. Build the powerup

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

pup 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.

3. Use powerup

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

pup use hello-world --name=world

4. 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:

npm publish

You may use the conventional commits preset to generate the changelog.

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

pup install npm: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.

./scripts/create-github-repo.sh

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

pup install git:github.com/<owner>/hello-world