pwa-sv - Svelte PWA Project Automation Tool

A CLI tool that streamlines the creation of typesafe Progressive Web App (PWA) projects using SvelteKit with a simple bun create pwa-sv command.

Features

• Quick Setup: Create a SvelteKit PWA project with a single command
• PWA Ready: Pre-configured with service worker, manifest, and caching strategies
• Vite Integration: Properly configured PWA plugin for Vite
• Package Scripts: Pre-configured development, build, and preview scripts
• Functional Programming Ready: Includes Effect library and functional programming patterns
• Type-Safe Error Handling: Uses Effect's powerful error handling capabilities for type-safe operations
• Optional Features:
  • Skeleton UI Framework (with --skeleton or -s flag)
  • Internationalization Support (with --i18n or -i flag)
  • Dexie IndexedDB Wrapper (with --dexie or -d flag)
  • Playwright Browser Testing (with --playwright or -p flag)
  • Git Repository Initialization (with --git or -g flag, enabled by default)

Note: pwa-asset-generator is automatically included in all projects created by pwa-sv as a devDependency for generating PWA icons and assets.

Installation & Usage

Creating a New Project

bun create pwa-sv my-pwa-project
# or
npm create pwa-sv my-pwa-project
# or
pnpm create pwa-sv my-pwa-project

Using Command-Line Flags

# Create project with Skeleton UI
bun create pwa-sv my-pwa-project --skeleton
# Or using short flag
bun create pwa-sv my-pwa-project -s

# Create project with internationalization support
bun create pwa-sv my-pwa-project --i18n
# Or using short flag
bun create pwa-sv my-pwa-project -i

# Create project with Dexie for IndexedDB
bun create pwa-sv my-pwa-project --dexie
# Or using short flag
bun create pwa-sv my-pwa-project -d

# Create project with Playwright browser testing
bun create pwa-sv my-pwa-project --playwright
# Or using short flag
bun create pwa-sv my-pwa-project -p

# Create project with multiple optional features
bun create pwa-sv my-pwa-project --skeleton --i18n --dexie --playwright

# Use non-interactive mode (accept all defaults)
bun create pwa-sv my-pwa-project --yes

# Skip Git initialization (default: true)
bun create pwa-sv my-pwa-project --no-git

Additional Options

• Git Initialization: By default, Git is initialized with an initial commit. Use the --no-git flag to skip Git repository initialization.
• Playwright Testing: By default, Playwright is not installed. Use the --playwright (or -p) flag to include Playwright browser testing in your project.
• Vitest Defaults: When unit or component testing is selected, the --defaults flag is automatically used to bypass interactive prompts and automatically select both unit and component testing.

Available Scripts

After project creation, these scripts are available in your package.json:

• bun build-pwa-assets: Generate PWA icons and assets
• bun i18n:extract: Extract translation keys (if i18n enabled)
• bun i18n:check: Check for missing translations (if i18n enabled)

How to Use pwa-asset-generator

The pwa-asset-generator tool is included in your project to automatically generate PWA icons and assets from a single source image.

Setup

1. Prepare your source icon: Place a high-quality PNG image at src/lib/assets/pwa-icon.png (recommended size: 1024x1024px with transparency support)

2. Generate assets: Run the following command:

   bun build-pwa-assets

3. Generated assets: The tool will create various icon sizes and formats automatically:

   • Transparent icons (64px, 192px, 512px)
   • Favicons (48px, .ico format)
   • Maskable icons (512px)
   • Web manifest icons and link tags

Configuration

The generator is configured via pwa-assets.config.ts in your project root. The default configuration:

• Generates Android and web assets only (iOS assets are excluded)
• Uses the 2023 preset for modern PWA standards
• Automatically updates your manifest and HTML head links

Notes

• Run bun build-pwa-assets again after updating src/lib/assets/pwa-icon.png to regenerate all assets
• The configuration is pre-configured and typically doesn't require modification

Project Structure

The generated project follows SvelteKit conventions with additional PWA-specific configurations:

my-pwa-project/
├── package.json           # Scripts and dependencies configured

├── vite.config.ts        # Vite config with PWA plugin
├── svelte.config.js      # SvelteKit configuration
├── tailwind.config.cjs   # Tailwind CSS with Skeleton UI (if enabled)
├── src/                  # SvelteKit application code
│   ├── lib/              # Reusable components, modules, etc.
│   │   ├── i18n/         # Internationalization config (if enabled)
│   │   └── locales/      # Translation files (if enabled)
│   ├── routes/           # Page routes
│   └── app.html          # Application shell
├── static/               # Static assets directory
└── Configuration files (tsconfig.json, etc.)

Configuration

PWA Configuration

The vite.config.ts file includes the PWA plugin with service worker and manifest configuration. The manifest is automatically configured with default values.

Internationalization (i18n)

When the --i18n flag is used, the project includes:

• svelte-i18n for internationalization
• Pre-configured English and Spanish locale files
• A sample component showing how to use translations
• Scripts for extracting and checking translations

Skeleton UI

When the --skeleton flag is used, the project includes:

• Tailwind CSS configured with Skeleton UI
• Proper component aliases
• A sample component showing how to use Skeleton UI components

Functional Programming Features

The generated SvelteKit PWA projects now include support for functional programming patterns using the Effect library. This provides:

• Type-safe error handling with Effect's powerful error management
• Resource management with automatic cleanup capabilities
• Concurrent operations with Effect's concurrency model
• Effectful computations with proper handling of side effects
• Development tools with integrated Effect Platform for comprehensive utilities

For more details on using functional programming in your generated applications, see the functional programming documentation.

Development

This project uses modern development tooling for efficient, high-quality code:

Tooling Stack

• Editor: Zed IDE (high-performance, native editor)
• Linting: Biome (fast linter and formatter)
• Code Quality: www.ultracite.ai (AI-powered linting rules)
• AI Assistant: OpenCode (intelligent development agent)
• Package Manager: bun (fast package manager)
• Testing: Vitest (unit and integration testing)

Available Scripts

bun run build       # Build project with TypeScript
bun run dev         # Watch mode for development
bun run test        # Run tests with Vitest
bun run test:watch  # Run tests in watch mode

Code Quality

bun run lint        # Run Biome linter
bun run format      # Format code with Biome

For detailed information about our development tools and workflow, see Development Tools Documentation.

Contributing

Contributions are welcome! This project was created using a comprehensive development workflow based on user stories and epics to ensure a well-architected, maintainable codebase.

Publishing

To publish this CLI tool to npm as pwa-sv, please follow the steps in the publishing guide.

Recent Changes

v1.3.0 (2026-01-13)

New Features

• Added optional Git initialization during project creation with --git or -g flag
• Git repository is automatically initialized with an initial commit when enabled
• Improved error handling for Git initialization failures

v1.2.0 (2026-01-12)

Bug Fixes

• Fixed rollback logging in engine.ts - added proper rollback messages for project creation and dependency installation steps
• Added German (de.json) and French (fr.json) locale files to i18n configuration
• Fixed test expectations to match actual error message patterns
• Updated structure validation tests to handle Windows path separators correctly

Testing

• Improved test coverage for rollback operations
• Enhanced mock handling for path-dependent operations
• Test suite now at ~90% passing rate

GitLab CI/CD Integration

Added comprehensive GitLab CI/CD configuration for automated testing, building, and publishing:

• Automated testing on every push and merge request
• Build verification and artifact storage
• Automated publishing to npm registries
• Documentation deployment

See the publishing guide for more information.

Package Information

This tool is published as create-pwa-sv on npm. Install it using:

bun create pwa-sv my-project
# or
npm create pwa-sv my-project
# or
pnpm create pwa-sv my-project

About EduTherapy

This tool is developed by EduTherapy (a brand of Talim Shifa Studio), specializing in digital transformation for education and healthcare sectors through Progressive Web Apps.

• 🌐 Website: https://eduth.pro/
• 📧 Contact: [email protected]

License

MIT