create-bl-theme

create-bl-theme

CLI tool to scaffold Better Lyrics themes.

Installation

npm install -g create-bl-theme

Or use directly with npx:

npx create-bl-theme@latest my-theme

Usage

Create a new theme

create-bl-theme [theme-name]

The CLI will prompt you for:

• Theme ID (lowercase, hyphens allowed)
• Theme title
• Description
• Your GitHub username
• Tags (dark, light, minimal, colorful, etc.)
• Whether to include shaders

Validate a theme

# Validate a local directory
create-bl-theme validate ./my-theme

# Validate directly from a GitHub repository
create-bl-theme validate https://github.com/username/theme-repo

The validator checks:

• Required files (metadata.json, style.rics or style.css, images/)
• RICS syntax validation (for .rics files)
• Valid JSON structure and required fields
• Semver version format
• Image integrity (detects corrupted files)
• Image dimensions (recommends 1280x720, but other sizes work fine)

Bump version

# Bump patch version (1.0.0 → 1.0.1)
create-bl-theme bump patch

# Bump minor version (1.0.0 → 1.1.0)
create-bl-theme bump minor

# Bump major version (1.0.0 → 2.0.0)
create-bl-theme bump major

# Bump in a specific directory
create-bl-theme bump patch ./my-theme

Check publishing status

# Check if theme is registered and ready to publish
create-bl-theme publish

# Check a specific directory
create-bl-theme publish ./my-theme

The publish command:

• Checks if your theme is registered in the theme store
• Shows your current version vs. the registry version
• Provides setup instructions for auto-publishing

Generated Structure

my-theme/
├── metadata.json    # Theme metadata (required)
├── style.rics       # Your styles in RICS format (required)
├── DESCRIPTION.md   # Rich description (optional, takes precedence)
├── shader.json      # Shader config (if enabled)
├── README.md        # Theme documentation
└── images/          # Screenshots (required)
    └── preview.png

RICS

Themes use RICS - a lightweight CSS preprocessor with full CSS parity. RICS adds variables, nesting, and mixins while staying close to standard CSS.

Any valid CSS is also valid RICS, so you can write plain CSS if you prefer.

$accent: #ff6b6b;

.lyrics-container {
  background: rgba(0, 0, 0, 0.8);

  .lyrics-line {
    color: $accent;

    &.active {
      font-weight: bold;
    }
  }
}

• Playground: https://rics.boidu.dev
• RICS Docs: https://github.com/better-lyrics/rics

Note: Both .rics and .css files are supported. The validator prefers .rics if both exist.

Theme Description Options

You can provide your theme description in two ways:

• description field in metadata.json - Simple, inline description for basic themes
• DESCRIPTION.md file - For richer descriptions with formatting (recommended for longer descriptions)

If both exist, DESCRIPTION.md takes precedence. At least one must be present.

Better Lyrics supports GitHub Flavored Markdown (GFM) in DESCRIPTION.md, so you can use:

• Bold, italic, and other text formatting
• Links and images
• Lists, tables, and code blocks
• Any other GFM features

Theme Development

• Edit style.rics - Add your custom styles using RICS or plain CSS. Use browser DevTools to inspect Better Lyrics elements and find the right selectors.

• Add screenshots - Place at least one preview image in images/. Recommended size: 1280x720 (16:9 aspect ratio).

• Update metadata.json - Ensure all fields are correct before submission.

• Test locally - Install your theme via "Install from URL" in Better Lyrics using your local path or GitHub repo URL.

Resources:

• Styling Guide - Available selectors and styling reference

Submitting to Theme Store

• Push your theme to a GitHub repository
• Fork themes
• Add your theme to index.json:

  {
    "themes": [
      { "repo": "your-username/your-theme-repo" }
    ]
  }
  

• Open a pull request

Auto-Publishing

After your theme is registered, install the Better Lyrics Themes GitHub App on your repo. This enables automatic updates:

• Bump your version: create-bl-theme bump patch
• Commit and push
• The registry automatically validates and publishes your update

Use create-bl-theme publish to check your publishing status.

License

MIT