inodaf / pwa-kit

🔭 A Production-Ready Frontend Development Kit with Next.js + TypeScript.

PWA Kit · Enterprise Apps

Starting a new Web App needs to be easy. PWA Kit provides a fully featured environment with Next.js + TypeScript and let you focus on code delivery without compromising best practices.

The Stack

Base

• ⚡️ Next.js with TypeScript + Paths
• 📱 First Class PWA Support
• 🍃 Application Properties for Production, Staging and Development
• 👩‍🎤 CSS Styling with TailwindCSS or CSS Modules
• ⚛️ Support for React Query
• 🔒 Automatic local HTTPS with Caddy

Quality

• 🧑‍🔬 Testing with Jest + swc + @testing-library + Coverage Reports
• 🐞 Linting with TypeScript ESLint
• 📝 Code Format with Prettier
• 🥸 GraphQL and REST API mocking with MSW
• 🌲 E2E Tests with Playwright

Security

• 👮‍♂️ Support for Content-Security-Policy
• 🔍 CI Sec Inspection with Mozilla Observatory soon

Accessibility

• 🧏‍♀️ Linting JSX a11y with eslint-plugin-jsx-a11y
• 🪓 Testing with Axe Core soon

Performance

• 📊 Core Web Vitals Report
• 🚥 Lighthouse CI + Bundlesize soon

CI + Deployment

• 📍 GitHub Actions for Test, Lint and Format
• 🚀 Deployment + Branch Preview soon

---

Getting Started

Base commands for develop, test and build.

Requirements

• Node.js Toolchain Manager: Volta
• Package Manager: pnpm
• HTTP(S) Web Server: Caddy *optional

Prepare Development

A Makefile is used to orchestrate the installation of required tooling and dependencies. Open your Terminal app and run the command bellow, then you are able to get started. Make sure to install Caddy to enable HTTPS on Dev.

make

Note

In case of failure, head to the Troubleshooting section below for alternatives.

Development Server

The next command will spawn the Dev Server and load the environment variables from .env.

pnpm dev        # spawns the Dev Server at http://localhost:3000
pnpm dev:secure # spawns Caddy and the Dev Server at https://localhost:3000

Testing

There are Integration, Unit and E2E tests available and the matching test environment variables (.env.test) are automatically loaded. With the exception of E2E tests, these commands are also used for CI environments.

# Unit & Integration Tests
pnpm test     # run tests without watch
pnpm test:w   # run tests with watch
pnpm test:c   # run tests with coverage
pnpm t        # alias for `pnpm test`

# E2E Tests
pnpm test:e2e # runs with **dev server** as Base URL

Linting & Code Formatting

We split the process into Check and Fix commands.

# Linting
pnpm lint:check # checks linting without fixing (useful for CI)
pnpm lint       # checks linting and fixes issues

# Code Formatting
pnpm fmt:check # checks formatting without fixing (useful for CI)
pnpm fmt       # checks formatting and fixes issues

---

Environment Variables

Sensitive and secret data can be defined using Environment Variables. An .env file at the root directory can be used for storing these data. As per security .env files cannot be tracked through version control systems.

Application Properties

Application properties let you define environment-specific, static configuration for your system. Unlike Environment Variables, Properties cannot include sensitive values.

There are the base, dev, production and staging properties but it's possible to add many others, as they are named based on the value of APP_ENV and NEXT_PUBLIC_APP_ENV environment variable. Also they are separated by client and server.

The properties from base holds all the default configuration that applies for all environments. Overriding these values is made possible by using the environment specific property file, like dev.

In short, when APP_ENV and NEXT_PUBLIC_APP_ENV is set to production, base and production property files will be loaded and merged. Then they can be accessed through the application as bellow:

import { serverProperties } from "@/config/properties/server";
import { clientProperties } from "@/config/properties/client";

---

Building

Builds are separated by environments: Production and Staging. For both environments the NODE_ENV is set to production.

Production

pnpm build:prod # build with production bindings
pnpm start:prod # start the built app with production bindings

Staging

pnpm build:stag # build with staging bindings
pnpm start:stag # start the built app with staging bindings

Cleanup

Whenever you need a fresh start in case something is going wrong, you can leverage handy cleanup commands.

pnpm cleanup      # remove caches and temp files
pnpm cleanup:hard # same as above but also remove `node_modules`

---

Troubleshooting

Fail while using the make command: Behind the scenes this command depends on cURL for downloading Volta and pnpm binaries. Try installing cURL then run the command again. Also, the commands from Makefile are not supported on Windows machines so the alternative is to manually installing the required dependencies.

---

License

Although this template is MIT licensed, if needed, you must change the license after creating your project.

pwa-kit's Issues

To Dos

Performance

• Bundlesize
• Performance Budget
• Lighthouse CI

CI + Deployment

• Deployment + Preview with Netlify

Observability and Tracking

• Analytics with Google Analytics - Optional
• Observability with New Relic - Optional

Support for `i18n`

Setup SSR support for Internationalization (i18n)

—

Created via Raycast

PoC: Support for Monorepos using Turborepo

• Treat Next.js as a shell package, which open room for quick replace it to another alternative.

PoC: Replace Jest with Vitest

Security Lint and Tooling

TODO:

• Include CSP support;
• Integrate Mozilla Observatory with CI; https://observatory.mozilla.org/

Improve Workflow Execution Time

• Cache Node Dependencies
• Setup tests with the transpile only option

Monthly Package Upgrade PR Does not Triggers CI

Accessibility Lint and Tooling

• Linting with eslint-plugin-jsx-a11y
• Playwright with Axe on CI

Security: Check Exposed EnvVars

Double check private environment variables are not being exposed on the client production bundle.