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

1. Start the dev server:

superset-extensions dev

2. Configure Superset (superset_config.py):

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

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

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

Building

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

Deployment

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

Resources

• Extension Architecture
• API Reference
• Frontend Contribution Types
• GitHub Repository
• Community Forum