polar-kit

Experimental: This tool is currently in experimental status and may undergo breaking changes.

A CLI tool for creating, archiving, updating Polar products and prices and syncing them to your database.

Key Features:

• Product Management - Create, update, and archive Polar products and prices
• Database Sync - Sync Polar data to your database with adapters
• Multi-Environment - Built-in support for test, dev, staging, prod
• TypeScript - Full type safety with configuration files
• User Preferences - Remembers your last used environment and adapter

Quick Start:

npm install @makeco/polar-kit
yarn add @makeco/polar-kit
bun add @makeco/polar-kit

# Commands
create        # Create subscription plans in Polar
archive       # Archive subscription plans in Polar
update        # Update existing Polar plans
db sync       # Sync Polar plans to database
db purge      # Purge database plans
list products # List Polar products
list prices   # List Polar prices
urls          # Show Polar dashboard URLs
config        # View current user preferences

# Global Options
-c, --config <path>         # Path to polar.config.ts file (default: ./polar.config.ts)
-e, --env <environment>     # Target environment (test, dev, staging, prod)
-a, --adapter <name>        # Database adapter name

Configuration

Create a polar.config.ts file in your project root:

import { defineConfig } from "@makeco/polar-kit";

export default defineConfig({
  plans: [
    {
      product: {
        id: "pro-plan",
        name: "Pro Plan",
        description: "Professional features for growing teams",
      },
      prices: [
        {
          id: "pro-monthly",
          type: "recurring",
          amountType: "fixed",
          priceAmount: 2999,
          priceCurrency: "usd",
          recurringInterval: "month",
        },
        {
          id: "pro-yearly",
          type: "recurring",
          amountType: "fixed",
          priceAmount: 29999,
          priceCurrency: "usd",
          recurringInterval: "year",
        },
      ],
    },
  ],
  adapters: {
    // Custom property key. Can be postgres, sqlite, turso, myAdapter, etc.
    postgres: {
      syncProducts: async (products) => { /* Sync Polar products to your database */ },
      syncPrices: async (prices) => { /* Sync Polar prices to your database */ },
      clearProducts: async () => { /* Remove all products from your database */ },
      clearPrices: async () => { /* Remove all prices from your database */ },
      getProducts: async () => { /* Optional: Return all products from your database */ },
      getPrices: async () => { /* Optional: Return all prices from your database */ }
    },
  },
  env: {
    polarAccessToken: process.env.POLAR_ACCESS_TOKEN,
    polarOrganizationId: process.env.POLAR_ORGANIZATION_ID,
  },
});

Contributing

This project uses semantic-release for automated versioning and publishing. Commit messages must follow the Conventional Commits format.

Commit Format

<type>(<scope>): <description>

Version Bumps

| Commit Type | Version Bump | Example | |-------------|--------------|---------| | fix: | Patch (0.0.X) | fix: resolve null pointer in CLI | | feat: | Minor (0.X.0) | feat: add export command | | feat!: or BREAKING CHANGE: | Major (X.0.0) | feat!: change API signature |

Other Types (no release)

• chore: - maintenance tasks
• docs: - documentation changes
• refactor: - code refactoring
• test: - adding tests
• ci: - CI/CD changes

Examples

# Patch release (0.1.0 → 0.1.1)
git commit -m "fix: handle missing config file gracefully"

# Minor release (0.1.1 → 0.2.0)
git commit -m "feat: add JSON export format"

# Major release (0.2.0 → 1.0.0)
git commit -m "feat!: rename sync command to push"

License

MIT © makeco