Deployment Guide

Relevant source files

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

• vite.config.ts
• package.json
• index.html
• src/main.tsx
• tsconfig.json
• tsconfig.app.json
• README.md

This guide provides instructions on how to build and deploy the Character Sheet Maker application. The project is a "Local-First" web application built using React, TypeScript, and Vite. The deployment process involves compiling the source code into a set of static HTML, CSS, and JavaScript files, which can then be hosted on any static web server.

The core of the build and deployment process is managed through npm scripts defined in package.json and the Vite build tool. The process ensures that the TypeScript code is type-checked and then bundled into an optimized production-ready format.

1. Build Process

The build process is initiated by a single command which first type-checks the code and then bundles it for production.

Sources: package.json:7

Build Scripts

The project defines several npm scripts for development, building, and previewing the application. The key scripts for deployment are build and preview.

Script	Command	Description
dev	vite	Starts the development server with hot-reloading.
build	tsc -b && vite build	Compiles the application for production. It first runs the TypeScript compiler, then bundles with Vite.
lint	eslint .	Runs the ESLint linter over the project files.
preview	vite preview	Starts a local static web server to preview the production build from the dist directory.

Sources: package.json:5-9

Build Flow

The npm run build command executes a two-step process to create the production assets. First, it invokes the TypeScript compiler (tsc) to perform a type check without emitting files. If the type check is successful, it then runs vite build to bundle the application.

The following diagram illustrates the build process flow:

Sources: package.json:7, tsconfig.app.json:13

2. Configuration

The build process is configured through several files, primarily vite.config.ts for bundling and tsconfig.json for TypeScript compilation.

Vite Configuration

The vite.config.ts file configures the Vite build tool. It specifies the plugins used and sets up path aliases for cleaner imports.

• Plugins:
  • @vitejs/plugin-react-swc: Enables React support using the SWC compiler for fast transforms.
  • @tailwindcss/vite: Integrates Tailwind CSS into the Vite build process.
• Path Aliases:
  • An alias @{...} is configured to resolve to the src/{...} directory, simplifying import statements within the application.

// vite.config.ts
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react-swc";
import path from "path";
import { defineConfig } from "vite";

// https://vite.dev/config/
export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

Sources: vite.config.ts

TypeScript Configuration

The project uses a root tsconfig.json file that references more specific configuration files for the application and Node.js environment.

• tsconfig.app.json: Configures TypeScript for the React application source code located in the src directory. It sets the target to ES2022, enables JSX, and defines the path alias for @. The noEmit: true option indicates that tsc is used only for type checking, while Vite handles the transpilation.
• tsconfig.node.json: Configures TypeScript for Node.js-specific files like vite.config.ts.

// tsconfig.json
{
  "files": [],
  "references": [
    {
      "path": "./tsconfig.app.json"
    },
    {
      "path": "./tsconfig.node.json"
    }
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Sources: tsconfig.json, tsconfig.app.json

3. Application Entry Point

The build process starts from a single HTML file which acts as the application's entry point.

The following diagram shows how the application is loaded:

Sources: index.html:11, src/main.tsx:5, src/main.tsx:9

• index.html: This is the main HTML file. It contains a <div> with the ID root where the React application is mounted. It includes the main script /src/main.tsx.
• src/main.tsx: This TypeScript file is the entry point for the React application. It uses createRoot to render the main <App /> component into the root div.

Sources: index.html:10-11, src/main.tsx:9

4. Previewing the Production Build

After a successful build, the output is placed in the dist directory (by default). To verify the build before deployment, you can use the preview script.

npm run preview

This command starts a local static server that serves the files from the dist folder. This allows you to interact with the application exactly as it would appear in a production environment.

Sources: package.json:9

5. Deployment

The output of the npm run build command is a directory containing static assets. This directory (typically dist) is fully self-contained and can be deployed to any static hosting provider.

Common deployment targets include:

• GitHub Pages
• Vercel
• Netlify
• AWS S3 with CloudFront
• Any web server capable of serving static files (Nginx, Apache, etc.)

The project is described as a "Local-First" application, which implies that its core functionality operates on the client-side, making it an ideal candidate for static hosting.

Sources: README.md:9