Skip to content

create-theme.md

Latest commit

 

History

History
58 lines (40 loc) · 2.78 KB

create-theme.md

File metadata and controls

58 lines (40 loc) · 2.78 KB

create-theme

Scaffolds a new custom theme package (Astro-based) that you can use with spg build --theme.

spg create-theme <name> [options]

How it works

The command creates a new theme by copying the base theme template (bundled with the package) and customizing it with your theme name. The generated theme is a 1:1 copy of the modern theme that users are familiar with, including:

  • package.json, astro.config.ts, tsconfig.json
  • src/pages/index.astro (main entry point)
  • Full-featured components (Hero, GallerySection, PhotoSwipe lightbox, SubGalleries, CTA banner, Footer)
  • Responsive layouts with blurhash placeholders and AVIF/JPG support
  • Query parameter customization utilities
  • All configuration files (ESLint, Prettier, etc.)

The command:

  1. Copies all files from the bundled base theme template (excluding build artifacts like node_modules, .astro, dist, etc.)
  2. Updates package.json with your theme name
  3. Generates README.md for the new theme (from the template's README_BASE.md)

By default, the theme is created in ./themes/<name>. If you run the CLI from inside a monorepo workspace, it will prefer creating themes under the monorepo root ./themes/<name>.

Note: The base theme template is bundled with the simple-photo-gallery package, so spg create-theme works out of the box after installation. The template source is located at gallery/src/modules/create-theme/templates/base in the repository. For local development, if themes/base exists in your workspace root, it will be used as a fallback (allowing you to test template changes without modifying the bundled template).

Options

Option Description Default
-p, --path <path> Path where the theme should be created (directory must not exist) ./themes/<name>
-v, --verbose Show detailed output
-q, --quiet Only show warnings/errors
-h, --help Show command help

Examples

# Create ./themes/my-theme
spg create-theme my-theme

# Create in a custom directory
spg create-theme my-theme --path ./my-theme

# Build a gallery using the generated theme (local path)
spg build --theme ./themes/my-theme -g /path/to/gallery

Next steps

See the Custom Themes guide for:

  • Required theme structure
  • How the build process passes GALLERY_JSON_PATH / GALLERY_OUTPUT_DIR
  • How to run astro dev while developing a theme