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.

!NPM Version

!GitLab Last Commit

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

$3

``bash
bun create pwa-sv my-pwa-project


or

npm create pwa-sv my-pwa-project

or

pnpm create pwa-sv my-pwa-project
`

$3

`bash


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
`

$3

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

$3

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:
`bash
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

$3

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

$3

- 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:

$3

- 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)

$3

`bash
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
`

$3

`bash
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

$3

#### 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

$3

#### 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

$3

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:

`bash
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: edutherapystudio@gmail.com

License

MIT