Debugging Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• tsconfig.json
• src/app/page.tsx
• src/app/layout.tsx
• src/app/globals.css
• next.config.ts

This guide provides an overview of the debugging tools and workflows available within the TAF-SAF project. The project is bootstrapped with create-next-app, leveraging the built-in features of Next.js, TypeScript, and Tailwind CSS for an efficient development and debugging experience. The primary methods for debugging involve using the Next.js development server with its live-reloading capabilities, static analysis via TypeScript, and code quality checks with linting.

The core of the debugging workflow revolves around running the local development server, which provides instant feedback on code changes. By modifying files like src/app/page.tsx, developers can see updates immediately in their browser at http://localhost:3000. This rapid feedback loop is essential for identifying and resolving issues in UI components, styling, and application logic.

Development Server and Live Reloading

The primary tool for debugging during development is the Next.js development server. It is configured to use Turbopack for faster performance.

Sources: README.md:7-12, package.json:5-6

Starting the Server

To start the development server, run one of the following commands in your terminal:

npm run dev

This command executes next dev --turbopack as defined in package.json. Once started, the application will be available at http://localhost:3000.

Sources: README.md:9, package.json:6

Live Reloading Workflow

The development server features live reloading. Any changes saved in project files, such as the main page component, will be automatically reflected in the browser without needing a manual refresh. This is the fundamental debugging cycle for front-end changes.

• Entry Point: The main page can be edited by modifying src/app/page.tsx.
• Feedback: The page auto-updates as you edit the file.

This workflow allows for immediate visual confirmation of changes and quick iteration on UI and logic bugs.

The diagram below illustrates the live reloading process.

Static Analysis and Type Checking

The project uses TypeScript to enforce type safety, which helps catch a wide range of errors before the code is ever run. The configuration for the TypeScript compiler is located in tsconfig.json.

Sources: tsconfig.json, package.json:17-20

TypeScript Configuration

The tsconfig.json file is configured with strict settings to ensure code quality and prevent common errors.

Key settings for debugging include:

Option	Value	Description
strict	true	Enables all strict type-checking options.
noEmit	true	Prevents the compiler from outputting files, as Next.js handles the build process. This is for type-checking only.
esModuleInterop	true	Allows default imports from modules with no default export.
moduleResolution	bundler	Mimics how modern bundlers (like the one in Next.js) resolve modules.
paths	{"@/*": ["./src/*"]}	Defines a path alias for easier imports from the src directory.

Sources: tsconfig.json:3-14, 23-25

Using the path alias can simplify imports and make the codebase easier to navigate when debugging file references.

// tsconfig.json
"paths": {
  "@/*": ["./src/*"]
}

Sources: tsconfig.json:23-25

Linting

The project is set up with a linting script to analyze code for programmatic and stylistic errors. This is another layer of automated debugging that helps maintain code quality.

Running the Linter

To run the linter, use the following command:

npm run lint

This command executes next lint, which uses the built-in ESLint configuration for Next.js projects.

Sources: package.json:5, 9

The following table details the available scripts in package.json.

Script	Command	Description
dev	next dev --turbopack	Starts the development server with Turbopack.
build	next build	Creates an optimized production build of the application.
start	next start	Starts the production server after a build.
lint	next lint	Runs the ESLint linter to find and fix problems in the code.

Sources: package.json:5-9

Application Structure and Styling

Debugging UI and layout issues often requires understanding the application's structure and how styles are applied.

Component and Layout Structure

The application's structure is defined by Next.js App Router conventions.

1. src/app/layout.tsx: This is the root layout that wraps all pages. It is responsible for defining the <html> and <body> tags and applying global styles and fonts. In this project, it loads and applies the Geist and Geist_Mono fonts.
2. src/app/page.tsx: This is the main page component for the / route. It contains the primary content displayed to the user.
3. src/app/globals.css: This file contains global CSS styles and imports Tailwind CSS. It also defines CSS variables for theming (e.g., background and foreground colors for light and dark modes).

This diagram shows how the core files interact to render a page.

Debugging Styles

Styling issues can be debugged by:

1. Inspecting the CSS variables defined in :root within src/app/globals.css. These control the base colors for light and dark themes.
2. Checking the utility classes applied to elements in src/app/page.tsx and src/app/layout.tsx.
3. Using browser developer tools to inspect the computed CSS for specific elements and trace styles back to either globals.css or Tailwind's utility classes.

Sources: src/app/globals.css:3-15, src/app/page.tsx:5