Skip to main content
GitScope uses Vite as its build tool, providing fast development and optimized production builds. This guide explains the build configuration, process, and output structure.

​
Build Tool: Vite

Vite is a modern build tool that offers:
  • Lightning-fast Hot Module Replacement (HMR) during development
  • Optimized production builds using Rollup
  • Native ES modules support
  • Built-in support for React, TypeScript, CSS modules, and more
  • Zero-config setup with sensible defaults

​
Vite Configuration

The project’s build configuration is defined in vite.config.js:
vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/github-dashboard/',
})

​
Configuration Options

​
plugins
array
Array of Vite plugins. The @vitejs/plugin-react plugin enables React Fast Refresh and JSX transformation.
​
base
string
default:"/"
The base public path when served in production. Set to /github-dashboard/ to match the GitHub Pages subdirectory. Must match the repository name when deploying to GitHub Pages.
The base option is critical for GitHub Pages deployments. It ensures all asset paths (JS, CSS, images) are correctly resolved when the app is hosted in a subdirectory.

​
Build Scripts

The package.json defines several build-related scripts:
package.json
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "deploy": "npm run build && gh-pages -d dist"
  }
}

​
Script Descriptions

Starts the Vite development server with Hot Module Replacement (HMR).
npm run dev
  • Runs on http://localhost:5173 by default
  • Provides instant feedback on code changes
  • Shows detailed error messages in the browser
  • Supports source maps for debugging
Creates an optimized production build in the dist directory.
npm run build
Build process:
  1. Cleans the dist directory
  2. Transforms and bundles all source files
  3. Minifies JavaScript and CSS
  4. Optimizes assets (images, fonts, etc.)
  5. Generates hashed filenames for cache busting
  6. Creates source maps (optional)
Previews the production build locally before deployment.
npm run preview
  • Serves the dist directory on http://localhost:4173
  • Simulates production environment
  • Useful for testing before deploying
  • Does not include HMR or development features
Builds the project and deploys to GitHub Pages.
npm run deploy
This command:
  1. Runs npm run build to create production assets
  2. Uses gh-pages -d dist to publish the dist folder
  3. Pushes to the gh-pages branch automatically

​
Build Output Structure

The production build generates the following structure in the dist directory: 
dist/
├── index.html              # Entry HTML file with injected asset links
├── assets/
│   ├── index-[hash].js     # Main JavaScript bundle (minified)
│   ├── index-[hash].css    # Compiled and minified CSS
│   └── [asset]-[hash].svg  # Optimized SVG assets
└── [other-static-files]    # Additional public assets

​
Output Characteristics

​
index.html
file
The main HTML entry point with:
  • Minified HTML
  • Inline critical CSS (optional)
  • Preload hints for faster loading
  • Hashed asset references for cache busting
​
assets/*.js
bundle
Optimized JavaScript bundles:
  • Tree-shaken to remove unused code
  • Minified with Terser
  • Code-split by route or component (when configured)
  • Hashed filenames for long-term caching
​
assets/*.css
stylesheet
Compiled CSS with:
  • CSS Modules transformed to scoped class names
  • Minified and compressed
  • Unused styles removed
  • Hashed filenames

​
Build Optimizations

Vite applies several optimizations automatically:

​
Code Splitting

  • Vendor dependencies bundled separately
  • Dynamic imports create separate chunks
  • Reduces initial load time

​
Tree Shaking

  • Removes unused code from final bundle
  • Only includes imported functions and components
  • Significantly reduces bundle size

​
Minification

  • JavaScript minified with esbuild (fast) or Terser (smaller)
  • CSS minified with Lightning CSS
  • HTML whitespace removed

​
Asset Optimization

  • Images can be optimized with plugins
  • SVGs are inlined when small enough
  • Fonts are subset when possible

​
Cache Busting

  • All assets get content-based hashes in filenames
  • index-a1b2c3d4.js changes only when content changes
  • Enables long-term caching with Cache-Control: max-age=31536000

​
Build Performance

Typical build times for GitScope: 
$ npm run dev
vite v5.0.8 dev server running at:

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

  ready in 245 ms

​
Build Analysis

To analyze your bundle size and dependencies:
1

Install rollup-plugin-visualizer

npm install --save-dev rollup-plugin-visualizer
2

Update vite.config.js

vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig({
  plugins: [
    react(),
    visualizer({ open: true })
  ],
  base: '/github-dashboard/',
})
3

Run Build

npm run build
A browser window will open showing an interactive visualization of your bundle composition.

​
Environment-Specific Builds

Vite uses environment variables prefixed with VITE_ that are exposed to your client code: 
# .env.production
VITE_API_URL=https://api.github.com
src/config.js
const apiUrl = import.meta.env.VITE_API_URL
GitScope does not currently use environment variables, as all configuration is handled through the GitHub API token stored in localStorage. If you add environment variables, never commit sensitive data like tokens or secrets.

​
Troubleshooting Build Issues

​
Build Fails with Memory Error

JavaScript heap out of memory
Increase Node.js memory limit:
package.json
{
  "scripts": {
    "build": "node --max-old-space-size=4096 ./node_modules/vite/bin/vite.js build"
  }
}

​
Assets Not Loading in Production

Verify the base path in vite.config.js matches your deployment subdirectory.

​
CSS Modules Not Working

Ensure files use the .module.css extension:
  • Header.module.css ✓
  • Header.css ✗

​
Large Bundle Size

  1. Use rollup-plugin-visualizer to identify large dependencies
  2. Consider code splitting with dynamic imports
  3. Remove unused dependencies from package.json
  4. Use lighter alternatives for heavy libraries

​
Next Steps

GitHub Pages Deployment

Deploy your built application to GitHub Pages

Environment Setup

Configure your local development environment

Build docs developers (and LLMs) love

Get started for freeTalk to us