PWAKit

Disclaimer: This project is in active development. APIs and features may change.

Turn your Progressive Web App into a native iOS app with full access to native capabilities.

PWAKit wraps your web app in a native iOS shell, providing a JavaScript bridge to access device features like haptics, biometrics, push notifications, HealthKit, and more.

Why PWAKit?

PWAKit wraps your existing Progressive Web App in a thin native iOS shell. Unlike frameworks that require learning new languages or rewriting your app, your code stays 100% web. For detailed comparisons with Capacitor, React Native, Flutter, and native Swift, see docs/comparison.md.

Features

• Native iOS App: Full App Store distribution with native performance
• JavaScript Bridge: Access iOS capabilities from your web code
• 15 Native Modules: Haptics, notifications, biometrics, secure storage, and more
• TypeScript SDK: Fully typed APIs for all native features
• JSON Configuration: Easy setup without Swift knowledge
• iOS 15+ Support: Broad device compatibility

Quick Start

Prerequisites

Tool	Version	Installation
macOS	14+ (Sonoma)	-
Xcode	15.0+	App Store
Swift	6.0+	Included with Xcode
SwiftFormat	0.54+	brew install swiftformat
SwiftLint	0.54+	brew install swiftlint

Setup in 3 Steps

# 1. Clone the repository
git clone https://github.com/eddmann/pwa-kit.git
cd pwa-kit

# 2. Configure your PWA
make kit/setup

# 3. Open in Xcode and run
make kit/open
# Then press Cmd+R in Xcode to build and run

The setup wizard will prompt for:

• App Name: Display name of your app
• Start URL: Your PWA's URL (must be HTTPS)
• Bundle ID: iOS bundle identifier (e.g., com.example.app)

Configuration

PWAKit uses a JSON configuration file at kit/src/PWAKit/Resources/pwa-config.json.

Minimal Configuration

{
  "version": 1,
  "app": {
    "name": "My App",
    "bundleId": "com.example.app",
    "startUrl": "https://app.example.com/"
  },
  "origins": {
    "allowed": ["app.example.com"]
  }
}

See docs/configuration.md for feature flags, Info.plist setup, and entitlements. See docs/config-schema.md for the complete schema reference.

Installation

CLI

npx @pwa-kit/cli init

JavaScript SDK

npm install @pwa-kit/sdk

Basic Usage

import { push, badging, haptics, ios, isNative } from "@pwa-kit/sdk";

if (isNative) {
  // Subscribe to push notifications
  const subscription = await push.subscribe();
  console.log("Token:", subscription.token);

  // Set app badge
  await badging.setAppBadge(5);

  // Haptic feedback
  await haptics.impact("medium");

  // iOS-specific: Face ID / Touch ID
  const result = await ios.biometrics.authenticate("Confirm purchase");
}

See sdk/README.md for the complete SDK documentation and API reference.

Native Modules

PWAKit includes 15 native modules:

Module	Description	SDK API
Platform	Device info	platform.getInfo()
App	Lifecycle, reviews	ios.app.requestReview()
Haptics	Haptic feedback	haptics.impact('medium')
Push Notifications	Remote push (APNs)	push.subscribe()
Local Notifications	Scheduled notifications	ios.notifications.schedule()
Biometrics	Face ID / Touch ID	ios.biometrics.authenticate()
Secure Storage	Keychain	ios.secureStorage.set()
Clipboard	Copy/paste	clipboard.writeText()
Share	Share sheet	share.share()
Print	AirPrint	print.print()
Camera Permission	Camera access	permissions.request({ name: 'camera' })
Microphone Permission	Microphone access	permissions.request({ name: 'microphone' })
Location Permission	Location access	permissions.request({ name: 'geolocation' })
HealthKit	Health data	ios.healthKit.querySteps()
StoreKit	In-app purchases	ios.storeKit.purchase()

For full API documentation, see sdk/README.md. To create your own modules, see docs/custom-modules.md.

Development

Run make help to see all available commands. Key commands:

make kit/setup      # Run interactive setup wizard
make kit/open       # Open Xcode project (Cmd+R to run, Cmd+U to test)
make example/serve  # Run kitchen sink demo server
make docs/dev       # Run user-facing docs site locally
make kit/lint       # Run SwiftLint
make kit/fmt        # Format code with SwiftFormat

For device testing, debugging, and deployment, see docs/development.md.

User Docs Site

PWAKit includes a user-facing static docs site in docs-site/.

make docs/deps
make docs/dev

Build static output:

make docs/build

Engineering Docs

Document	Description
Configuration Guide	Info.plist keys, entitlements, and feature flag setup
Config Schema	Complete JSON schema reference for pwa-config.json
Framework Comparison	PWAKit vs Capacitor, React Native, Flutter, and native Swift
Custom Modules	Guide to creating your own native bridge modules
Architecture	Internal architecture, bridge protocol, and message flow
Development	Local development, device testing, and debugging
Troubleshooting	Common issues and their solutions
SDK Reference	TypeScript SDK documentation and API reference

License

MIT License - see LICENSE for details.