tessl/npm-mapbox--mapbox-gl-style-spec

Specification and utilities for working with Mapbox GL styles including validation, migration, formatting, and expression evaluation

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

CLI Tools

Name: tessl/npm-mapbox--mapbox-gl-style-spec
Author: tessl

Command-line utilities for batch processing, validation, formatting, and migration of Mapbox GL style files. These tools enable automation workflows and integration with build systems.

Available Commands

The package provides four CLI tools accessible after installation:

gl-style-validate - Validate style files against specification
gl-style-format - Format and prettify style JSON files
gl-style-migrate - Migrate older style versions to current specification
gl-style-composite - Composite multiple vector sources into single source

Installation and Access

npm install -g @mapbox/mapbox-gl-style-spec

# Or use with npx without global installation
npx @mapbox/mapbox-gl-style-spec <command>

Capabilities

Style Validation Tool

Validates Mapbox GL style files against the specification with detailed error reporting.

Command: gl-style-validate

Usage:

gl-style-validate [options] <style-file>

Options:

--json - Output errors in JSON format instead of human-readable text
--mapbox-api-supported - Validate Mapbox API compatibility (checks for unsupported features)

Examples:

# Basic validation
gl-style-validate my-style.json

# JSON output for programmatic processing
gl-style-validate --json my-style.json

# Check Mapbox API compatibility
gl-style-validate --mapbox-api-supported my-style.json

# Combine options
gl-style-validate --json --mapbox-api-supported my-style.json

Exit Codes:

0 - Style is valid
1 - Style has validation errors

Output Format:

Human-readable (default):

✓ Style is valid

JSON format (--json):

{
  "valid": true,
  "errors": []
}

With errors:

{
  "valid": false,
  "errors": [
    {
      "message": "layers[0]: missing required property \"type\"",
      "line": 12
    }
  ]
}

Style Formatting Tool

Formats style JSON files with proper key ordering and consistent indentation.

Command: gl-style-format

Usage:

gl-style-format [options] <style-file>

Options:

--space <number> - Number of spaces for indentation (default: 2, use 0 for minified output)

Examples:

# Format with default 2-space indentation
gl-style-format my-style.json

# Format with 4-space indentation
gl-style-format --space 4 my-style.json

# Minify (single line, no formatting)
gl-style-format --space 0 my-style.json

# Format and save to new file
gl-style-format my-style.json > formatted-style.json

Key Ordering:

The formatter ensures consistent key ordering for better diffing and version control:

version
name
metadata
sources
sprite
glyphs
layers
transition
light/lights
terrain
fog

Style Migration Tool

Migrates older style versions to the current specification format.

Command: gl-style-migrate

Usage:

gl-style-migrate <style-file>

Supported Migrations:

Mapbox GL v7 styles to v8
Legacy function syntax to expression syntax
Deprecated property names to current equivalents

Examples:

# Migrate v7 style to v8
gl-style-migrate v7-style.json

# Migrate and save to new file
gl-style-migrate old-style.json > migrated-style.json

Migration Changes:

Updates version field from 7 to 8
Converts function-based properties to expressions
Updates deprecated layer types and properties
Modernizes filter syntax
Updates source configurations for v8 compatibility

Source Composition Tool

Composites multiple Mapbox vector sources into a single optimized source.

Command: gl-style-composite

Usage:

gl-style-composite <style-file>

Examples:

# Composite vector sources
gl-style-composite multi-source-style.json

# Composite and save result
gl-style-composite style.json > composited-style.json

Compositing Process:

Identifies multiple Mapbox vector tile sources
Combines them into a single composite source
Updates layer source references
Optimizes for reduced HTTP requests

Integration Examples

Build System Integration

package.json scripts:

{
  "scripts": {
    "validate-styles": "gl-style-validate src/styles/*.json",
    "format-styles": "gl-style-format --space 2 src/styles/*.json",
    "migrate-styles": "gl-style-migrate legacy-styles/*.json",
    "build-styles": "npm run migrate-styles && npm run format-styles && npm run validate-styles"
  }
}

CI/CD Pipeline

.github/workflows/styles.yml:

name: Style Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
      - run: npm install -g @mapbox/mapbox-gl-style-spec
      - run: gl-style-validate --json styles/*.json

Batch Processing

#!/bin/bash
# Process all style files in a directory

STYLE_DIR="./styles"
OUTPUT_DIR="./processed-styles"

mkdir -p "$OUTPUT_DIR"

for style in "$STYLE_DIR"/*.json; do
    filename=$(basename "$style")
    echo "Processing $filename..."
    
    # Migrate, format, and validate
    gl-style-migrate "$style" | \
    gl-style-format --space 2 > "$OUTPUT_DIR/$filename"
    
    # Validate the result
    if gl-style-validate "$OUTPUT_DIR/$filename"; then
        echo "✓ $filename processed successfully"
    else
        echo "✗ $filename has validation errors"
    fi
done

Programmatic Usage

While these are CLI tools, you can also invoke them programmatically:

const { execSync } = require('child_process');

function validateStyle(stylePath) {
  try {
    const result = execSync(`gl-style-validate --json "${stylePath}"`, {
      encoding: 'utf8'
    });
    return JSON.parse(result);
  } catch (error) {
    // Handle validation errors
    return JSON.parse(error.stdout);
  }
}

function formatStyle(stylePath, spaces = 2) {
  return execSync(`gl-style-format --space ${spaces} "${stylePath}"`, {
    encoding: 'utf8'
  });
}

Error Handling

All CLI tools use standard exit codes and provide detailed error messages:

Exit Codes:

0 - Success
1 - Validation/processing errors
2 - Invalid command line arguments

Common Error Scenarios:

File Not Found:

$ gl-style-validate nonexistent.json
Error: ENOENT: no such file or directory, open 'nonexistent.json'

Invalid JSON:

$ gl-style-validate invalid.json
Error: Unexpected token } in JSON at position 123

Validation Errors:

$ gl-style-validate --json invalid-style.json
{
  "valid": false,
  "errors": [
    {"message": "sources: required property missing", "line": 1}
  ]
}

Performance Considerations

Large Files: Tools handle large style files efficiently but may require additional memory
Batch Processing: Use shell loops or build tools for processing multiple files
JSON Parsing: Tools use optimized JSON parsing with detailed error location reporting
Validation Caching: Consider caching validation results for unchanged files in build systems