title: Extension CLI sidebar_position: 1

Superset Extension CLI

The apache-superset-extensions-cli package provides command-line tools for creating, developing, and packaging Apache Superset extensions. It streamlines the entire extension development workflow from initialization to deployment.

Installation

Install the CLI globally using pip:

pip install apache-superset-extensions-cli

Or install locally in your project:

pip install --user apache-superset-extensions-cli

Verify installation:

superset-extensions --version
# Output: apache-superset-extensions-cli version 1.0.0

Commands Overview

Command	Description
`init`	Create a new extension project
`dev`	Start development mode with hot reload
`build`	Build extension assets for production
`bundle`	Package extension into a .supx file
`validate`	Validate extension metadata and structure
`publish`	Publish extension to registry (future)

Command Reference

init

Creates a new extension project with the standard structure and boilerplate code.

superset-extensions init [options] <extension-name>

Options

--type, -t <type> - Extension type: full (default), frontend-only, backend-only
--template <template> - Project template: default, sql-lab, dashboard, chart
--author <name> - Extension author name
--description <desc> - Extension description
--license <license> - License identifier (default: Apache-2.0)
--superset-version <version> - Minimum Superset version (default: 4.0.0)
--skip-install - Skip installing dependencies
--use-typescript - Use TypeScript for frontend (default: true)
--use-npm - Use npm instead of yarn

Examples

# Create a basic extension
superset-extensions init my-extension

# Create a SQL Lab focused extension
superset-extensions init query-optimizer --template sql-lab

# Create frontend-only extension
superset-extensions init custom-viz --type frontend-only

# Create with metadata
superset-extensions init data-quality \
  --author "Jane Doe" \
  --description "Data quality monitoring for SQL Lab"

Generated Structure

my-extension/
├── extension.json          # Extension metadata
├── frontend/              # Frontend source code
│   ├── src/
│   │   ├── index.tsx     # Main entry point
│   │   └── components/   # React components
│   ├── package.json
│   ├── tsconfig.json
│   └── webpack.config.js
├── backend/               # Backend source code
│   ├── src/
│   │   └── my_extension/
│   │       ├── __init__.py
│   │       └── api.py
│   ├── tests/
│   └── requirements.txt
├── README.md
└── .gitignore

dev

Starts development mode with automatic rebuilding and hot reload.

superset-extensions dev [options]

Options

--port, -p <port> - Development server port (default: 9001)
--host <host> - Development server host (default: localhost)
--watch-backend - Also watch backend files (default: true)
--watch-frontend - Also watch frontend files (default: true)
--no-open - Don't open browser automatically
--superset-url <url> - Superset instance URL (default: http://localhost:8088)
--verbose - Enable verbose logging

Examples

# Start development mode
superset-extensions dev

# Use custom port
superset-extensions dev --port 9002

# Connect to remote Superset
superset-extensions dev --superset-url https://superset.example.com

Development Workflow

Start the dev server:

superset-extensions dev

Configure Superset (superset_config.py):

LOCAL_EXTENSIONS = [
    "/path/to/your/extension"
]
ENABLE_EXTENSIONS = True

Start Superset:

superset run -p 8088 --with-threads --reload

The extension will automatically reload when you make changes.

build

Builds extension assets for production deployment.

superset-extensions build [options]

Options

--mode <mode> - Build mode: production (default), development
--analyze - Generate bundle analysis report
--source-maps - Generate source maps
--minify - Minify output (default: true in production)
--output, -o <dir> - Output directory (default: dist)
--clean - Clean output directory before build
--parallel - Build frontend and backend in parallel

Examples

# Production build
superset-extensions build

# Development build with source maps
superset-extensions build --mode development --source-maps

# Analyze bundle size
superset-extensions build --analyze

# Custom output directory
superset-extensions build --output build

Build Output

dist/
├── manifest.json          # Build manifest
├── frontend/
│   ├── remoteEntry.[hash].js
│   ├── [name].[hash].js
│   └── assets/
└── backend/
    └── my_extension/
        ├── __init__.py
        └── *.py

bundle

Packages the built extension into a distributable .supx file.

superset-extensions bundle [options]

Options

--output, -o <file> - Output filename (default: {name}-{version}.supx)
--sign - Sign the bundle (requires configured keys)
--compression <level> - Compression level 0-9 (default: 6)
--exclude <patterns> - Files to exclude (comma-separated)
--include-dev-deps - Include development dependencies

Examples

# Create bundle
superset-extensions bundle

# Custom output name
superset-extensions bundle --output my-extension-latest.supx

# Signed bundle
superset-extensions bundle --sign

# Exclude test files
superset-extensions bundle --exclude "**/*.test.js,**/*.spec.ts"

Bundle Structure

The .supx file is a ZIP archive containing:

my-extension-1.0.0.supx
├── manifest.json
├── extension.json
├── frontend/
│   └── dist/
└── backend/
    └── src/

validate

Validates extension structure, metadata, and compatibility.

superset-extensions validate [options]

Options

--strict - Enable strict validation
--fix - Auto-fix correctable issues
--check-deps - Validate dependencies
--check-security - Run security checks

Examples

# Basic validation
superset-extensions validate

# Strict mode with auto-fix
superset-extensions validate --strict --fix

# Full validation
superset-extensions validate --check-deps --check-security

Validation Checks

Extension metadata completeness
File structure conformity
API version compatibility
Dependency security vulnerabilities
Code quality standards
Bundle size limits

Configuration File

Create .superset-extension.json for project-specific settings:

{
  "build": {
    "mode": "production",
    "sourceMaps": true,
    "analyze": false,
    "parallel": true
  },
  "dev": {
    "port": 9001,
    "host": "localhost",
    "autoOpen": true
  },
  "bundle": {
    "compression": 6,
    "sign": false,
    "exclude": [
      "**/*.test.*",
      "**/*.spec.*",
      "**/tests/**"
    ]
  },
  "validation": {
    "strict": true,
    "autoFix": true
  }
}

Environment Variables

Configure CLI behavior using environment variables:

# Superset connection
export SUPERSET_URL=http://localhost:8088
export SUPERSET_USERNAME=admin
export SUPERSET_PASSWORD=admin

# Development settings
export EXTENSION_DEV_PORT=9001
export EXTENSION_DEV_HOST=localhost

# Build settings
export EXTENSION_BUILD_MODE=production
export EXTENSION_SOURCE_MAPS=true

# Registry settings (future)
export EXTENSION_REGISTRY_URL=https://registry.superset.apache.org
export EXTENSION_REGISTRY_TOKEN=your-token

Advanced Usage

Custom Templates

Create custom project templates:

# Use custom template
superset-extensions init my-ext --template https://github.com/user/template

# Use local template
superset-extensions init my-ext --template ./my-template

CI/CD Integration

GitHub Actions

name: Build Extension

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.9'

      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: '16'

      - name: Install CLI
        run: pip install apache-superset-extensions-cli

      - name: Install dependencies
        run: |
          npm install --prefix frontend
          pip install -r backend/requirements.txt

      - name: Validate
        run: superset-extensions validate --strict

      - name: Build
        run: superset-extensions build --mode production

      - name: Bundle
        run: superset-extensions bundle

      - name: Upload artifact
        uses: actions/upload-artifact@v2
        with:
          name: extension-bundle
          path: '*.supx'

Automated Deployment

Deploy extensions automatically:

#!/bin/bash
# deploy.sh

# Build and bundle
superset-extensions build --mode production
superset-extensions bundle --sign

# Upload to Superset instance
BUNDLE=$(ls *.supx | head -1)
curl -X POST "$SUPERSET_URL/api/v1/extensions/import/" \
  -H "Authorization: Bearer $SUPERSET_TOKEN" \
  -F "bundle=@$BUNDLE"

# Verify deployment
curl "$SUPERSET_URL/api/v1/extensions/" \
  -H "Authorization: Bearer $SUPERSET_TOKEN"

Multi-Extension Projects

Manage multiple extensions in one repository:

# Initialize multiple extensions
superset-extensions init extensions/viz-plugin --type frontend-only
superset-extensions init extensions/sql-optimizer --template sql-lab
superset-extensions init extensions/auth-provider --type backend-only

# Build all extensions
for dir in extensions/*/; do
  (cd "$dir" && superset-extensions build)
done

# Bundle all extensions
for dir in extensions/*/; do
  (cd "$dir" && superset-extensions bundle)
done

Troubleshooting

Common Issues

Port already in use

# Error: Port 9001 is already in use

# Solution: Use a different port
superset-extensions dev --port 9002

Module not found

# Error: Cannot find module '@apache-superset/core'

# Solution: Ensure dependencies are installed
npm install --prefix frontend

Build failures

# Check Node and Python versions
node --version  # Should be 16+
python --version  # Should be 3.9+

# Clear cache and rebuild
rm -rf dist node_modules frontend/node_modules
npm install --prefix frontend
superset-extensions build --clean

Bundle too large

# Warning: Bundle size exceeds recommended limit

# Solution: Analyze and optimize
superset-extensions build --analyze

# Exclude unnecessary files
superset-extensions bundle --exclude "**/*.map,**/*.test.*"

Debug Mode

Enable debug logging:

# Set debug environment variable
export DEBUG=superset-extensions:*

# Or use verbose flag
superset-extensions dev --verbose
superset-extensions build --verbose

Getting Help

# General help
superset-extensions --help

# Command-specific help
superset-extensions init --help
superset-extensions dev --help

# Version information
superset-extensions --version

Best Practices

Development

Use TypeScript for type safety
Follow the style guide for consistency
Write tests for critical functionality
Document your code with JSDoc/docstrings
Use development mode for rapid iteration

Building

Optimize bundle size - analyze and tree-shake
Generate source maps for debugging
Validate before building to catch issues early
Use production mode for final builds
Clean build directory to avoid stale files

Deployment

Sign your bundles for security
Version properly using semantic versioning
Test in staging before production deployment
Document breaking changes in CHANGELOG
Provide migration guides for major updates

title: Extension CLI sidebar_position: 1

Superset Extension CLI

Installation

Commands Overview

Command Reference

init

Options

Examples

Generated Structure

dev

Options

Examples

Development Workflow

build

Options

Examples

Build Output

bundle

Options

Examples

Bundle Structure

validate

Options

Examples

Validation Checks

Configuration File

Environment Variables

Advanced Usage

Custom Templates

CI/CD Integration

GitHub Actions

Automated Deployment

Multi-Extension Projects

Troubleshooting

Common Issues

Port already in use

Module not found

Build failures

Bundle too large

Debug Mode

Getting Help

Best Practices

Development

Building

Deployment

Resources