Offline First Todo App

A learning project exploring offline-first PWA architecture
Built with Next.js, Serwist, and TanStack Query

📖 Read the Tutorial »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
2. Tech Stack
3. Getting Started
   • Prerequisites
   • Installation
4. Usage
5. Contributing
6. License

About The Project

This project was born out of necessity while building a warehouse management system in a remote area of Kazakhstan. The internet there was unreliable or nonexistent, yet the app needed to be fully functional—allowing workers to scan products and tag locations without interruption.

I found plenty of resources on PWAs (Service Workers) and separate resources on State Management (TanStack Query), but very few on how to combine them effectively for a true "Offline First" experience.

This repository serves as that missing link: a reference implementation demonstrating how to merge Serwist (for app shell caching) and TanStack Query (for data persistence and mutation queueing).

Core Capabilities:

• App Shell Caching: Loads instantly even after a hard refresh without network (via Serwist).
• Data Persistence: Reads cached data immediately when offline (via TanStack Query Persister).
• Mutation Queueing: Queues actions (Create/Update/Delete) while offline and replays them automatically when connectivity is restored.
• Optimistic UI: Updates the interface immediately, treating offline actions as "success" until proven otherwise.

(back to top)

Tech Stack

• Framework: Next.js (App Router)
• PWA/Service Worker: Serwist
• State Management: TanStack Query (with Persister)
• Storage: LocalForage (IndexedDB wrapper)
• Database: PostgreSQL (via Drizzle ORM)
• Styling: Tailwind CSS & Shadcn UI

(back to top)

Getting Started

To get a local copy up and running, follow these steps.

Prerequisites

• Node.js (v18+)
• pnpm

  npm install -g pnpm

• Docker (Optional, for running PostgreSQL)

Installation

1. Clone the repo

   git clone https://github.com/nomomon/offline-first-todo-app.git
   cd offline-first-todo-app

2. Install packages

   pnpm install

3. Set up environment variables. Create a .env file in the root directory:

   DATABASE_URL="postgresql://postgres:postgres@localhost:5432/todo_app"
   NEXTAUTH_SECRET="your_super_secret_key"
   NEXTAUTH_URL="http://localhost:3000"
   GITHUB_ID=""
   GITHUB_SECRET=""

4. Start the database (using Docker Compose)

   docker-compose up -d db

5. Run database migrations

   pnpm db:migrate

6. Start the development server

   pnpm dev

(back to top)

Usage

Once running, the application acts as a fully offline-capable PWA.

1. Offline Simulation: Open the browser DevTools, go to the Network tab, and set it to "Offline".
2. CRUD Actions: Create, edit, or delete todos. Notice the UI updates immediately.
3. Sync: Re-enable the network. You will see the pending requests fire automatically to sync with the server.

(back to top)

License

Distributed under the MIT License.

(back to top)

Contact

Mansur Nurmukhambetov - @nomomon

Project Link: https://github.com/nomomon/offline-first-todo-app