Skip to main content

The nextjs-web Directory

This page explains every file and directory in /home/nextjs-web and how they're actually used in the development workflow.

Core Directories​

apps/​

Contains all deployable Next.js applications. Each subdirectory is a complete Next.js application that can be built and deployed independently.

Used for: Housing the actual web applications that get deployed to production Contains: beacon-docs, client-central/, client.schwab.com/, docs/, meganav-mfe/, nextapi.schwab.com/, nexttools.schwab.com/, sanity-next, sanity-studio/, storybook/, www.schwab.com/

packages/​

Contains shared code libraries that can be imported by applications in apps/.

Used for: Code reuse across multiple applications, avoiding duplication Contains: cli/, fetch/, mock-data/, processors/, schema/, security/, server-actions/, test/, transformer/, tsconfig/, twconfig/, ui/, utilities/

node_modules/​

Auto-generated directory containing all installed dependencies.

Used for: Storing all npm packages used across the monorepo Generated by: pnpm install command Size: Large (generated, not committed to git)

Configuration Files​

package.json​

Root package file defining workspace-level scripts and dependencies.

Key contents:

  • "name": "nextjs-web" - Project identifier
  • "version": "0.1.576" - Current version number
  • Scripts section: Contains commands like build, dev, clean, test
  • Workspace configuration: Defines this as the root of a pnpm workspace

Most used commands:

pnpm build          # Builds all apps using Turbo
pnpm dev            # Starts all apps in development mode
pnpm clean          # Removes all node_modules directories
pnpm clean-next     # Removes all .next build directories

pnpm-workspace.yaml​

Defines which directories are part of the pnpm workspace.

Contents:

packages:
  - "apps/*"
  - "packages/*"

Used for: Telling pnpm that every directory in apps/ and packages/ is a separate package that can depend on each other

pnpm-lock.yaml​

Lock file containing exact versions of all installed dependencies.

Used for: Ensuring everyone gets exactly the same dependency versions Generated by: pnpm install Size: Large (1.4MB) - contains entire dependency tree

turbo.json​

Configuration for Turborepo, the build system that orchestrates building multiple packages.

Used for:

  • Defining build pipelines
  • Caching build results
  • Running tasks in parallel across multiple packages
  • Optimizing CI/CD performance

biome.jsonc​

Configuration for Biome, the linting and formatting tool.

Used for:

  • Code formatting rules (replaces Prettier)
  • Linting rules (replaces ESLint)
  • Enforcing consistent code style across the monorepo

jest.config.ts​

Root Jest configuration for testing.

Used for: Defining how tests run across the entire monorepo TypeScript file because it exports configuration programmatically

conformance.config.jsonc​

Configuration for Vercel's conformance tool.

Used for: Enforcing architectural and performance rules during builds Vercel-specific tool that prevents common mistakes in Next.js apps

postcss.config.js​

Configuration for PostCSS, the CSS processing tool.

Used for: Transforming CSS (autoprefixer, Tailwind CSS processing, etc.)

vercel.json​

Configuration for Vercel deployment platform.

Contents: Minimal configuration for deployment settings Used for: Controlling how the project deploys to Vercel

Hidden Directories (Dotfiles)​

.git/​

Git repository data and history.

Used for: Version control, branches, commit history Contains: All git metadata, hooks, and configuration

.next/​

Build output directory created by Next.js.

Used for: Storing compiled Next.js application code Generated by: next build commands Should not be committed to git (in .gitignore)

.turbo/​

Turborepo cache directory.

Used for: Caching build results to speed up subsequent builds Generated by: Turbo during builds Persists between builds to maintain cache effectiveness

.vercel/​

Vercel CLI configuration and project settings.

Used for: Storing Vercel project configuration and deployment tokens Generated by: Vercel CLI when linking projects

.github/​

GitHub-specific configuration files.

Used for:

  • GitHub Actions workflows (CI/CD)
  • Issue and PR templates
  • Repository configuration

.vscode/​

VS Code workspace configuration.

Used for:

  • Shared editor settings for the project
  • Recommended extensions list
  • Debugging configurations
  • IDE setup scripts

.allowlists/​

Contains exception lists for various tools.

Current file: REQUIRE_ONE_VERSION_POLICY.allowlist.json Used for: Allowing specific packages to have multiple versions when normally prohibited

Individual Files​

.node-version​

Specifies the exact Node.js version to use.

Contents: v20.9 Used by: Node version managers (nvm, asdf, etc.) to automatically switch to the correct version

.gitignore​

Lists files and directories that Git should ignore.

Used for: Preventing build artifacts, dependencies, and sensitive files from being committed

.prettierignore​

Lists files that Prettier should not format.

Used for: Excluding generated files or special formats from automatic formatting

.vercel.approvers​

Lists who can approve Vercel deployments.

Used for: Deployment approval workflow in CI/CD

CONTRIBUTING.md​

Guidelines for contributing to the project.

Used for: Documenting how developers should contribute code, report issues, and submit PRs

README.md​

Main project documentation and getting started guide.

Used for: Project overview, setup instructions, and basic usage

� How These Files Work Together​

Development Workflow​

  1. .node-version ensures everyone uses the same Node version
  2. pnpm-workspace.yaml defines the monorepo structure
  3. package.json provides commands to work with the entire workspace
  4. turbo.json orchestrates builds across multiple packages
  5. .vscode/ provides consistent editor experience

Build Process​

  1. pnpm install reads package.json and pnpm-workspace.yaml
  2. pnpm build triggers turbo.json configuration
  3. Turbo builds packages in correct dependency order
  4. .next/ directories store build outputs
  5. .turbo/ caches results for faster subsequent builds

Code Quality​

  1. biome.jsonc defines formatting and linting rules
  2. jest.config.ts configures testing framework
  3. conformance.config.jsonc enforces architectural rules
  4. .allowlists/ contains exceptions to strict rules