Gasket Next.js Express Template

A full-stack TypeScript web application template built with Gasket, Next.js Pages Router, Express custom server, and internationalization support.

Overview

This template provides a production-ready starting point for building web applications using:

• Next.js 15 with Pages Router - React framework with file-based routing
• Express Custom Server - Full control over server-side rendering and API routes
• TypeScript - Type-safe development with modern JavaScript features
• Gasket - Plugin architecture for extensible applications
• React Intl - Internationalization with multi-language support
• Vitest - Lightning-fast unit testing with React Testing Library

Features

• ✅ Next.js Pages Router with TypeScript support
• ✅ Custom Express server for advanced server-side control
• ✅ Internationalization pre-configured with English and French
• ✅ Server-side rendering with Gasket data injection
• ✅ API routes and custom server endpoints capability
• ✅ Testing setup with Vitest, React Testing Library, and JSDOM
• ✅ ESLint configuration with React and Next.js rules
• ✅ Development tools with hot reloading and TypeScript watching
• ✅ Production build optimization

Quick Start

Create a new Next.js Pages Router project with custom Express server:

npx create-gasket-app@latest my-app --template @gasket/template-nextjs-express

Project Structure

my-app/
├── pages/                 # Next.js Pages Router
│   ├── _app.tsx           # App component wrapper
│   ├── _document.ts       # Document component
│   └── index.tsx          # Home page component
├── components/            # React components
│   └── head.tsx           # Reusable head component
├── locales/               # Internationalization files
│   ├── en-US.json         # English translations
│   └── fr-FR.json         # French translations
├── test/                  # Test files
├── gasket.ts              # Gasket configuration
├── server.ts              # Custom Express server
├── intl.ts                # Internationalization manager
├── next.config.js         # Next.js configuration
├── tsconfig.json          # TypeScript configuration
└── dist/                  # Built server files

Available Scripts

| Script | Description | |--------|-------------| | npm run local | Start development with TypeScript watch and custom server | | npm run build | Build TypeScript server and Next.js application | | npm run start | Start production server | | npm run preview | Build and start production server | | npm run test | Run unit tests | | npm run test:watch | Run tests in watch mode | | npm run test:coverage | Run tests with coverage report | | npm run docs | Generate and serve documentation | | npm run lint | Check code style and quality |

Development

Custom Express Server

The template includes a custom Express server (server.ts) that wraps Next.js, giving you full control over:

• Server-side rendering - Custom SSR logic and data fetching
• API routes - Express routes alongside Next.js API routes
• Middleware - Custom middleware for authentication, logging, etc.
• Error handling - Custom error pages and handling logic

The development setup runs two concurrent processes:

1. TypeScript Watch - Compiles server TypeScript files on change
2. Custom Express Server - Runs Next.js with GASKET_DEV=1 for development mode

Pages Router vs App Router

This template uses Next.js Pages Router, which differs from App Router:

• File-based routing in the pages/ directory
• _app.tsx for global app wrapper and providers
• _document.ts for HTML document structure
• getServerSideProps and getStaticProps for data fetching
• API routes in pages/api/ directory

Internationalization

The template includes full i18n support with React Intl and @gasket/react-intl.

Pages and Components

App Component (pages/_app.tsx)

The app component wraps all pages and includes:

• IntlProvider for internationalization
• Router-based locale detection
• Global providers and context

Document Component (pages/_document.ts)

Enhanced with Gasket data injection using withGasketData:

import Document from 'next/document';
import { withGasketData } from '@gasket/nextjs/document';
import gasket from '@/gasket';

export default withGasketData(gasket)(Document);

Adding New Pages

Create new pages in the pages/ directory:

// pages/about.tsx
import Head from '../components/head';
import { FormattedMessage } from 'react-intl';

export default function AboutPage() {
  return (
    <div>
      <Head title="About" description="About our app" />
      <h1><FormattedMessage id="about_title" /></h1>
    </div>
  );
}

API Routes

Add API routes in pages/api/:

// pages/api/users.ts
import type { NextApiRequest, NextApiResponse } from 'next';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'GET') {
    res.status(200).json({ users: [] });
  } else {
    res.setHeader('Allow', ['GET']);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
}

Configuration

The template includes these Gasket plugins by default:

• @gasket/plugin-nextjs - Next.js integration
• @gasket/plugin-express - Express custom server
• @gasket/plugin-intl - Internationalization support
• @gasket/plugin-https - HTTPS and server lifecycle management
• @gasket/plugin-webpack - Webpack configuration
• @gasket/plugin-winston - Structured logging
• @gasket/plugin-command - CLI command support

Custom Server Routes

Add custom Express routes in your server.ts or via Gasket plugins:

// Example plugin for custom routes
export default {
  name: 'api-routes',
  hooks: {
    express(gasket, app) {
      app.get('/api/custom', (req, res) => {
        res.json({ message: 'Custom API endpoint' });
      });
    }
  }
};

Testing

The template includes comprehensive testing setup:

• Vitest - Fast test runner
• React Testing Library - React component testing utilities
• JSDOM - DOM simulation for server-side testing
• TypeScript support - Type-safe tests

Write tests in the test/ directory:

import { render, screen } from '@testing-library/react';
import { IntlProvider } from 'react-intl';
import { describe, it, expect } from 'vitest';
import IndexPage from '@/pages/index';

const messages = {
  gasket_welcome: 'Welcome to Gasket!',
  gasket_learn: 'Learn Gasket',
  gasket_edit_page: 'To get started, edit pages/index.js and save to reload.'
};

describe('IndexPage', () => {
  it('renders welcome message', () => {
    render(
      <IntlProvider locale="en-US" messages={messages}>
        <IndexPage />
      </IntlProvider>
    );
    expect(screen.getByText('Welcome to Gasket!')).toBeInTheDocument();
  });
});

Next Steps

• Add more pages in the pages/ directory
• Create API routes in pages/api/
• Add custom Express middleware and routes
• Customize the internationalization with additional languages
• Add database connections and authentication
• Set up CI/CD pipeline
• Add more comprehensive testing