Skip to main content

​
Prerequisites

Before starting, ensure you have:
  • Node.js 18+ or Bun runtime installed
  • Git for version control
  • A code editor (VS Code recommended)

​
Installation

1

Clone the repository

git clone <repository-url>
cd vite_react_shadcn_ts
2

Install dependencies

Using npm:
npm install
Or using Bun (faster):
bun install
3

Start the development server

npm run dev
The application will be available at http://localhost:5173
The dev server runs on port 5173 by default and listens on all network interfaces (::), allowing access from other devices on your network.

​
Development Workflow

​
Hot Module Replacement (HMR)

Vite provides blazing-fast HMR powered by React SWC for instant updates:
  • Changes to React components refresh immediately
  • CSS updates apply without full page reload
  • State is preserved during updates when possible
  • HMR overlay is disabled for a cleaner development experience
The project uses @vitejs/plugin-react-swc which provides faster refresh times compared to the standard Babel transform.

​
Path Aliases

The @ alias points to the src directory for cleaner imports: 
// Instead of:
import { Button } from '../../../components/ui/button'

// Use:
import { Button } from '@/components/ui/button'
Configured in vite.config.ts:16-18: 
resolve: {
  alias: {
    "@": path.resolve(__dirname, "./src"),
  },
}

​
Available npm Scripts

# Start development server with HMR
npm run dev

​
Running Tests with Vitest

​
Test Configuration

The project uses Vitest with jsdom for unit and component testing. Key configuration from vitest.config.ts:7-11: 
test: {
  environment: "jsdom",
  globals: true,
  setupFiles: ["./src/test/setup.ts"],
  include: ["src/**/*.{test,spec}.{ts,tsx}"],
}

​
Writing Tests

Tests are located in src/test/ and follow the pattern *.test.ts or *.spec.tsx: 
import { describe, it, expect } from "vitest";

describe("example", () => {
  it("should pass", () => {
    expect(true).toBe(true);
  });
});

​
Test Setup

The src/test/setup.ts:1 file imports @testing-library/jest-dom for enhanced matchers and configures window.matchMedia mock for testing components that use media queries.
Tests run in a jsdom environment. Browser-specific APIs may need additional mocking.

​
Code Linting with ESLint

​
ESLint Configuration

The project uses the modern flat config format with TypeScript ESLint. From eslint.config.js:7-25: 
export default tseslint.config(
  { ignores: ["dist"] },
  {
    extends: [js.configs.recommended, ...tseslint.configs.recommended],
    files: ["**/*.{ts,tsx}"],
    plugins: {
      "react-hooks": reactHooks,
      "react-refresh": reactRefresh,
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
      "@typescript-eslint/no-unused-vars": "off",
    },
  },
);

​
Enabled Plugins

  • react-hooks: Enforces Rules of Hooks
  • react-refresh: Ensures components are HMR-compatible
  • typescript-eslint: TypeScript-specific linting rules

​
Running the Linter

# Check for linting errors
npm run lint

# Auto-fix issues (when possible)
npm run lint -- --fix

​
Troubleshooting

Port Already in Use

If port 5173 is already in use, either kill the process or modify the port in vite.config.ts:9.

Module Resolution Errors

Ensure path aliases are configured in both vite.config.ts and tsconfig.json. The @ alias must point to ./src.

Tests Failing

Check that @testing-library/jest-dom is imported in src/test/setup.ts:1 and Vitest is using the jsdom environment.

​
Next Steps

Project Structure

Learn about the directory organization and file conventions

Building & Deploying

Build for production and deploy to hosting platforms

Build docs developers (and LLMs) love

Get started for freeTalk to us