CLI tool to automate the creation of typesafe Progressive Web App (PWA) projects using SvelteKit
A CLI tool that streamlines the creation of typesafe Progressive Web App (PWA) projects using SvelteKit with a simple bun create pwa-sv command.
- 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.
``bash`
bun create pwa-sv my-pwa-projector
npm create pwa-sv my-pwa-projector
pnpm create pwa-sv my-pwa-project
`bashCreate project with Skeleton UI
bun create pwa-sv my-pwa-project --skeletonOr using short flag
bun create pwa-sv my-pwa-project -s
$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 modificationProject 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 translationsSkeleton 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
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
``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
MIT