EasyPWA Documentation

Welcome to the EasyPWA documentation. This guide will help you build beautiful Progressive Web Apps without writing any code.

New to EasyPWA?

Start with our Quick Start Guide to create your first app in under 5 minutes!

What is a PWA?

A Progressive Web App (PWA) is a type of web application that uses modern web technologies to deliver app-like experiences to users. PWAs combine the best of web and native apps.

Key Benefits of PWAs

Installable

Users can install your PWA directly from the browser - no app store needed.

Works Offline

Service workers cache your app for offline access and fast loading.

Fast & Reliable

PWAs load instantly and respond quickly to user interactions.

Cross-Platform

One codebase works on iOS, Android, Windows, Mac, and more.

Quick Start Guide

Follow these simple steps to create your first PWA in under 5 minutes:

1

Create an Account

Sign up for free at easypwa.xyz/register. No credit card required.

2

Create a New Project

Click "Create New PWA" and enter your app name, choose colors, and upload an icon (or use a generated one).

3

Add Your Content

Use the visual editor to add pages, navigation tabs, and configure features like maps and authentication.

4

Preview & Publish

Use the Preview feature to test your app on iOS and Android simulators, then publish to your free subdomain.

Creating an Account

Getting started with EasyPWA is completely free. Here's what you need to know:

  • No credit card required - ever
  • Create unlimited PWA apps
  • Each app gets a free SSL-secured subdomain
  • Your account includes all features with no restrictions

Account Security

We use secure password hashing and sessions to protect your account. For best security, use a strong, unique password.

Creating a Project

When you create a new PWA project, you'll need to provide some basic information:

Field Description Required
App Name The full name of your app (e.g., "My Restaurant App") Yes
Description A brief description of what your app does No
Theme Color Primary color used in the header and UI elements Yes
Background Color Splash screen and app background color Yes
Display Mode How the app appears (standalone, fullscreen, etc.) Yes
Orientation Portrait, landscape, or any orientation Yes
App Icon 512x512 PNG or JPG image for your app icon No

Subdomain Assignment

When you create a project, EasyPWA automatically assigns a unique subdomain (e.g., happy-mountain.easypwa.xyz). This is auto-generated to ensure uniqueness.

App Settings

After creating your project, you can customize various settings in the "App Settings" tab:

Basic Settings

  • App Name & Short Name: Update how your app appears on devices
  • Description: Brief text shown in app stores and sharing previews
  • Theme Color: Changes the browser toolbar and UI accent color
  • Background Color: Shown during app launch splash screen

Advanced Settings

  • Display Mode: Choose standalone (recommended), fullscreen, minimal-ui, or browser
  • Orientation: Lock to portrait, landscape, or allow any
  • Start URL: The first page users see when opening your app
  • Language: Primary language code (e.g., "en", "es", "fr")

Static Pages

Static pages contain fixed content that you define. They're perfect for:

  • Home pages with welcome messages
  • About pages with company information
  • Contact pages with address and phone numbers
  • Menu pages for restaurants
  • Product listings
  • Terms of service and privacy policy

Creating a Static Page

  1. Go to the "Static Pages" tab in your project editor
  2. Click "Add Page"
  3. Enter a page title (e.g., "About Us")
  4. Set the route/URL (e.g., "about")
  5. Choose a page type (blank, text, card, etc.)
  6. Add your content using the HTML editor
  7. Click "Save" and your changes are automatically built

HTML Support

Static pages support full HTML content. You can use:

<h1>Welcome!</h1> <p>This is my awesome app.</p> <img src="image.jpg" alt="My image"> <a href="/contact">Contact Us</a>

Dynamic Pages

Dynamic pages fetch and display data from external APIs. They're useful for:

  • News feeds from RSS or JSON APIs
  • Product catalogs from e-commerce APIs
  • Event listings from calendar APIs
  • Social media feeds
  • Weather data

Configuring a Dynamic Page

  1. Go to the "Dynamic Pages" tab
  2. Click "Add Dynamic Page"
  3. Enter the page title and route
  4. Provide the API endpoint URL
  5. Configure how to display the data (list, grid, etc.)
  6. Map API response fields to display elements

Maps Integration

EasyPWA includes built-in support for interactive maps using Leaflet and OpenStreetMap. Perfect for location-based apps.

Enabling Maps

  1. Go to the "Maps" tab in your project editor
  2. Toggle "Enable Map Page"
  3. Set the default map center (latitude/longitude)
  4. Configure the zoom level (1-18)
  5. Optionally add markers with custom labels

Map Features

  • Interactive: Users can pan, zoom, and interact with the map
  • Custom Markers: Add location pins with labels
  • User Location: Optionally show the user's current location
  • No API Key Required: Uses free OpenStreetMap tiles

User Authentication

Add user login and registration to your PWA to create personalized experiences.

Enabling Authentication

  1. Go to "App Settings" tab
  2. Find the "Authentication" section
  3. Toggle "Enable User Authentication"
  4. Save your settings

When enabled, your app will include:

  • Login page with email/password form
  • Registration page for new users
  • Secure session management
  • Logout functionality

Offline Support

All EasyPWA apps include automatic offline support through service workers.

How It Works

  • Your app's HTML, CSS, JS, and icons are cached on first visit
  • When offline, the cached version is served
  • When online, the cache is automatically updated
  • Users see content instantly, even on slow connections

Cache Updates

Each time you rebuild your app, a new cache version is created. Users will automatically receive updates when they next visit your app online.

Install Prompt

Encourage users to install your PWA with a customizable install prompt banner.

Enabling Install Prompt

  1. Go to "App Settings" tab
  2. Find "Install Prompt" section
  3. Toggle "Show Install Prompt"
  4. Save your settings

Platform Behavior

  • Android/Chrome: Shows native install prompt with "Install" button
  • iOS/Safari: Shows instructions for "Add to Home Screen" via Share menu
  • Desktop: Shows install button in address bar and custom prompt

Theming & Colors

Customize the look and feel of your app with colors and styling options.

Theme Color

The theme color affects:

  • Header/toolbar background
  • Browser address bar color (on supported browsers)
  • Task switcher app preview color
  • Primary buttons and accents

Background Color

The background color is used for:

  • App splash screen while loading
  • Default page background
  • Consistent visual appearance during transitions

Previewing Your App

EasyPWA includes a built-in device simulator to preview your app before publishing.

Using the Preview

  1. Click the "Preview" button in your project
  2. Switch between iOS and Android views
  3. Navigate through your app using the bottom tabs
  4. Test different pages using the quick-access buttons

Live Preview

Changes are automatically rebuilt when you save. Refresh the preview to see your latest changes.

Building Your App

EasyPWA automatically builds your app whenever you make changes. You can also manually trigger a rebuild.

Auto-Build

Your app is automatically rebuilt when you:

  • Update app settings (name, colors, etc.)
  • Add, edit, or delete pages
  • Modify navigation items
  • Change map settings

Manual Rebuild

Click the blue "Rebuild" button in the header to force a fresh build. This ensures:

  • New cache version is generated
  • All files are regenerated
  • Service worker is updated

Your Subdomain

Every EasyPWA app gets a free subdomain on easypwa.xyz with automatic SSL.

Subdomain Format

Your subdomain is automatically generated using a memorable format:

https://happy-mountain.easypwa.xyz https://swift-river.easypwa.xyz https://bright-forest.easypwa.xyz

Features

  • Free SSL: HTTPS is enabled automatically
  • Always Online: Your app is hosted 24/7
  • Fast CDN: Content is served quickly worldwide
  • Share Anywhere: Share your URL on social media, business cards, etc.

Download & Self-Host

Want to host your PWA on your own server? Download it as a ZIP file!

Downloading Your App

  1. Build your app (if not already built)
  2. Click "Download ZIP" button
  3. Extract the ZIP file
  4. Upload to any web server

ZIP Contents

your-app/ ├── index.html # Main app HTML ├── manifest.json # PWA manifest ├── sw.js # Service worker └── assets/ └── icons/ # App icons (various sizes)

Hosting Requirements

  • HTTPS: PWAs require a secure connection
  • Static hosting: Any static file host works (Netlify, Vercel, GitHub Pages, etc.)
  • Proper MIME types: Ensure .json and .js files are served correctly

Service Worker

EasyPWA automatically generates a service worker (sw.js) that handles caching and offline functionality.

Caching Strategy

The service worker uses a "Cache First" strategy:

  1. Check if resource exists in cache
  2. If cached, serve immediately (fast!)
  3. If not cached, fetch from network
  4. Store fetched resource in cache for next time

Cache Versioning

Each build creates a unique cache name with a timestamp. This ensures:

  • Old caches are automatically cleaned up
  • Users receive updates when you publish changes
  • No stale content issues

Web App Manifest

The manifest.json file tells browsers how to install and display your PWA.

Generated Manifest

EasyPWA automatically generates a manifest with:

{ "name": "Your App Name", "short_name": "App", "description": "Your app description", "start_url": "/", "display": "standalone", "orientation": "portrait", "theme_color": "#22c55e", "background_color": "#ffffff", "icons": [ { "src": "assets/icons/icon-72.png", "sizes": "72x72" }, { "src": "assets/icons/icon-192.png", "sizes": "192x192" }, { "src": "assets/icons/icon-512.png", "sizes": "512x512" } ] }

Custom Hosting

Host your EasyPWA app on popular platforms:

Netlify

  1. Download your PWA as ZIP
  2. Go to netlify.com
  3. Drag and drop the extracted folder
  4. Your app is live with free SSL!

Vercel

  1. Download your PWA as ZIP
  2. Install Vercel CLI: npm i -g vercel
  3. Run vercel in the extracted folder
  4. Follow the prompts to deploy

GitHub Pages

  1. Create a new GitHub repository
  2. Upload your PWA files
  3. Go to Settings → Pages
  4. Enable GitHub Pages from main branch

Troubleshooting

Common issues and their solutions:

App not updating after changes

Cause: Old service worker cache

Solution: Click "Rebuild" to generate a new cache version. On mobile, close and reopen the app, or clear the browser cache.

Install prompt not showing

Cause: Browser criteria not met or user dismissed it

Solution: Ensure you're using HTTPS, clear localStorage, and visit the app fresh. Some browsers require multiple visits.

Map not showing

Cause: Map feature not enabled or incorrect coordinates

Solution: Go to Maps tab, ensure it's enabled, and verify the latitude/longitude values are correct.

Navigation tabs not appearing

Cause: No navigation items added

Solution: Go to Navigation tab and add at least one navigation item with a valid page link.

PWA not installable

Cause: Missing requirements for PWA installation

Solution: Ensure you have an app icon uploaded, valid manifest, and are accessing via HTTPS.

Need More Help?

Can't find what you're looking for? We're here to help!

Get Started Free