Local Development Setup

Relevant source files

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

• package.json
• README.md
• eslint.config.js
• scripts/optimize-images.js
• netlify.toml
• tsconfig.json

This document outlines the necessary steps and available tools for setting up and running the "2026 Gold Standard Portfolio" project locally. The project is a modern web application built with React 19 and Vite, architected using Feature-Sliced Design (FSD). The development environment is configured with a comprehensive set of scripts for running, building, linting, and optimizing the application.

The setup emphasizes performance and maintainability, leveraging Vite for a fast development server and build process. Code quality is enforced through a strict ESLint configuration that validates the FSD architecture, ensuring a scalable and decoupled codebase.

Sources: README.md, package.json

Prerequisites

Before starting, ensure you have a recent version of Node.js installed, as the project relies on it for package management and running scripts. The project uses an ES Module ("type": "module") structure.

Sources: package.json:5, scripts/optimize-images.js:4

Installation

To set up the local environment, clone the repository and install the required dependencies using a Node.js package manager like npm or yarn.

1. Clone the repository:

   git clone https://github.com/BonyKoshy/Portfolio.git
   cd Portfolio
   

2. Install dependencies:

   npm install
   

   This command will download all the dependencies and devDependencies listed in the package.json file, including React, Vite, ESLint, and TypeScript.

Sources: package.json:10-41

Available Scripts

The project includes several scripts defined in package.json to streamline development tasks.

Script	Description
dev	Starts the Vite development server on the default port.
dev:host	Starts the Vite development server and exposes it to the local network.
build	Creates a production-ready build of the application in the dist directory.
lint	Runs ESLint to analyze the codebase for potential errors and architectural violations.
preview	Starts a local static web server to preview the production build from the dist directory.
optimize-images	Converts .png and .jpg images in specific public directories to .webp format and deletes the originals.

Sources: package.json:6-11

Development and Build Flow

The following diagram illustrates the primary workflows for local development and creating a production build.

This diagram shows the distinct paths for running the development server, building the application for production, and previewing the final build.

Sources: package.json:6-11, netlify.toml:3, scripts/optimize-images.js

Code Quality and Linting

Code quality is maintained using ESLint, configured in eslint.config.js. The configuration is crucial for enforcing the project's Feature-Sliced Design (FSD) architecture.

Sources: eslint.config.js

FSD Boundary Enforcement

The ESLint setup includes the eslint-plugin-boundaries plugin to enforce strict dependency rules between the different layers of the FSD architecture (app, pages, widgets, features, entities, shared). This prevents "spaghetti dependencies" and ensures a unidirectional data flow.

The rules disallow lower layers from importing from higher layers. For example, the shared layer cannot import from entities, features, widgets, pages, or app.

The FSD layer hierarchy and import restrictions are visualized below.

This diagram illustrates the valid, top-down dependency flow in FSD and highlights examples of invalid import paths that the linter will flag as errors.

Sources: eslint.config.js:40-70

Key Linting Rules

• boundaries/element-types: Enforces the FSD architectural layers.
• @typescript-eslint/no-unused-vars: Warns about unused variables, ignoring those starting with an underscore or in all caps.
• react-refresh/only-export-components: Ensures Fast Refresh works correctly by warning if files with React components have non-component exports.

Sources: eslint.config.js:28-39

Asset Optimization

The project includes a custom script for optimizing images, which is crucial for web performance.

Image Optimization Script

The npm run optimize-images command executes the scripts/optimize-images.js script. This script uses the sharp library to perform the following actions:

1. Scans the /public/projects and /public/certs directories for images.
2. Converts any .png, .jpg, or .jpeg files to the modern .webp format.
3. Resizes images to a maximum width of 800px if they are larger.
4. Sets the WebP quality to 80.
5. Deletes the original image files after successful conversion.
6. It also processes profile-image.jpg or profile-image.png in the root of the public directory.

// scripts/optimize-images.js

// Configuration
const MAX_WIDTH = 800; // Resize large project screenshots
const QUALITY = 80;

async function processDirectory(directory) {
  // ...
  // ...
        const newFilePath = path.join(directory, `${name}.webp`);
  // ...
        let pipeline = image.webp({ quality: QUALITY });

        if (metadata.width > MAX_WIDTH) {
          pipeline = pipeline.resize({ width: MAX_WIDTH });
        }

        await pipeline.toFile(newFilePath);
  // ...
        // Delete original file
        await fs.promises.unlink(filePath);
  // ...
}

Sources: scripts/optimize-images.js:15-16, scripts/optimize-images.js:29-41

TypeScript Configuration

The project uses a strict TypeScript configuration defined in tsconfig.json to ensure type safety and code correctness.

Path Aliases

To simplify import paths and align with the FSD structure, a path alias is configured. Imports from the src directory can use the @/* prefix.

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

Strictness Flags

The configuration enables several strict flags to catch potential errors at compile time:

• "strict": true
• "noUncheckedIndexedAccess": true
• "noImplicitReturns": true
• "noUnusedLocals": true
• "noUnusedParameters": true

Sources: tsconfig.json:14-22

Deployment

The netlify.toml file configures the deployment process for Netlify. It specifies that the npm run build command should be executed to build the site, and the output dist directory should be published. It also includes configuration for redirects and security headers.

Sources: netlify.toml:2-3