Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Lou Gehrig Fan Club (LGFC) project is a modern web application built with Next.js (App Router) and TypeScript, specifically optimized for deployment on Cloudflare Pages. It consists of a public-facing website and an authenticated FanClub area, utilizing Cloudflare D1 for data management and Backblaze B2 for media assets.
This guide outlines the environment requirements, authentication procedures, and command-line operations necessary to initialize and run the repository locally or within a cloud-based development environment.
Sources: README.md:1-9, context.md:9-15
Development Environment Options
The project supports two primary development workflows: GitHub Codespaces for zero-config cloud environments and traditional local machine setup.
GitHub Codespaces
The repository is pre-configured for GitHub Codespaces, which automatically:
- Configures the development environment.
- Installs all required Node.js dependencies.
- Provides access to pre-installed tools like the GitHub CLI (
gh).
Sources: CONTRIBUTING.md:7-14, CONTRIBUTING.md:120-122
Local Prerequisites
To run the project locally, the following environment specifications are required:
- Node.js: Version
>=22but<23. - Package Manager:
npm. - Git: Configured with a valid username and email.
Sources: package.json:96-98, CONTRIBUTING.md:19-21, CONTRIBUTING.md:29-33
Initial Setup & Installation
To prepare the repository for development, execute the following commands in order:
# Clone the repository
git clone https://github.com/wdhunter645/next-starter-template.git
cd next-starter-template
# Install dependencies
npm install
Sources: package.json:16, CONTRIBUTING.md:21, README.md:46-47
Available NPM Scripts
The package.json file defines several key scripts for the development lifecycle:
| Script | Command | Description |
|---|---|---|
dev | next dev | Starts the Next.js development server. |
dev:cf | wrangler pages dev ... | Starts local Cloudflare Pages emulation with D1 bindings. |
build | rm -rf out .next && next build | Compiles the project for production. |
lint | next lint | Runs ESLint for code quality checks. |
test | vitest run | Executes unit and integration tests. |
test:e2e | playwright test | Runs end-to-end browser tests. |
Sources: package.json:37-64
Git Authentication & Security
GitHub no longer supports password authentication for Git operations; developers must use Personal Access Tokens (PAT) or SSH keys.
Authentication Flow
The following diagram illustrates the recommended authentication process using a Personal Access Token:
Sources: CONTRIBUTING.md:35-64, CONTRIBUTING.md:112-114
Git CLI (gh) Integration
For environments like Codespaces, using the GitHub CLI is the preferred method for managing authentication.
# Interactive login
gh auth login
Sources: CONTRIBUTING.md:120-127
Architecture & Data Flow
The project utilizes a hybrid architecture combining static site generation with dynamic API capabilities provided by Cloudflare.
System Architecture
The following diagram describes the relationship between the Next.js frontend, Cloudflare infrastructure, and external storage.
Sources: context.md:9-15, context.md:19-21, README.md:5-9
Infrastructure Configuration
Cloudflare Pages Snapshots
The repository includes automated tooling (scripts/cf_pages_snapshot.sh) to capture infrastructure state. This requires specific environment variables to be set in the development or CI environment:
| Variable | Description |
|---|---|
CF_ACCOUNT_ID | The Cloudflare Account Identifier. |
CF_PAGES_PROJECT | The name of the project in Cloudflare Pages. |
CLOUDFLARE_API_TOKEN | API token with permissions to read project metadata. |
Sources: scripts/cf_pages_snapshot.sh:12-24
Snapshot Generation Process
When the snapshot script is executed, it performs the following sequence:
Sources: scripts/cf_pages_snapshot.sh:76-102
Summary
Setting up the LGFC project locally requires Node.js v22 and a valid GitHub Personal Access Token for Git operations. Developers can choose between a standardized GitHub Codespaces environment or a local setup using npm install and npm run dev. The project architecture leverages Cloudflare Pages for hosting, D1 for data, and Next.js for the application framework, supported by various utility scripts for infrastructure auditing and snapshots.
Sources: CONTRIBUTING.md:7-27, context.md:9-15, package.json:96-98