Troubleshooting

Relevant source files

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

• package.json
• vite.config.ts
• tsconfig.json
• tsconfig.app.json
• tsconfig.node.json
• eslint.config.js
• src/lib/exportUtils.ts
• src/store/useSheetStore.ts
• src/components/sheet/BlockRenderer.tsx

This document provides guidance for diagnosing and resolving common issues that may arise during the development, build, and usage of the Character Sheet Maker application. It covers problems related to dependencies, build configuration, TypeScript, linting, and runtime feature errors. The project is built with React, TypeScript, and Vite, so troubleshooting steps are centered around this technology stack.

Environment and Build Issues

This section addresses problems related to the project's setup, dependencies, and the Vite build system.

Dependency Management

All project dependencies are managed in package.json. Issues in this area often manifest as errors during npm install or as Cannot find module errors at runtime.

Sources: package.json

Key Dependencies

Dependency	Version	Role	Potential Issues
react	^19.2.0	Core UI library	Version mismatches, hook errors.
vite	npm:rolldown-vite@7.2.5	Build tool and dev server	Build failures, HMR not working. Note the overrides section.
typescript	~5.9.3	Language superset	Type errors, compilation failures.
tailwindcss	^4.1.17	CSS framework	Styles not applying, JIT compilation issues.
react-grid-layout	^1.5.2	Grid layout system	Drag/resize issues, layout shifts.
html-to-image	^1.11.13	PNG export utility	Export failures, CORS issues with images.
jspdf	^3.0.4	PDF export utility	Malformed PDFs, incorrect dimensions.
zustand	^5.0.8	State management	State not updating or persisting.

Sources: package.json:11-28

NPM Scripts

The project uses several scripts for common tasks. Running the wrong script or having a misconfigured environment can lead to errors.

Script	Command	Description	Common Problems
dev	vite	Starts the development server with Hot Module Replacement (HMR).	Port conflicts, HMR not updating, Vite config errors.
build	tsc -b && vite build	First, type-checks the project, then creates a production build in the dist/ folder.	TypeScript errors halting the build, asset bundling failures.
lint	eslint .	Runs ESLint to check for code quality and style issues.	Linting errors preventing commits (if using pre-commit hooks).
preview	vite preview	Serves the production build from the dist/ folder locally.	404 errors if the build hasn't been run, routing issues.

Sources: package.json:6-10

Build & Development Server

Configuration for Vite is located in vite.config.ts. Misconfigurations here can lead to module resolution errors or problems with CSS processing.

The following diagram shows the path alias configuration which is a common source of "module not found" errors if not configured correctly in both Vite and TypeScript.

This diagram illustrates how path aliases are resolved.
Sources: vite.config.ts:8-12, tsconfig.app.json:26-28

A key part of the Vite configuration is the inclusion of plugins.

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

If you encounter issues with React Fast Refresh or Tailwind CSS styles not being applied, ensure the react() and tailwindcss() plugins are correctly imported and included.

Sources: vite.config.ts:6-7

TypeScript Configuration

The project uses a multi-layered TypeScript configuration. The root tsconfig.json acts as a solution-style file, referencing separate configurations for the application source code and Node.js-based tooling scripts.

This diagram shows the relationship between the TypeScript configuration files.
Sources: tsconfig.json:3-9, tsconfig.app.json:31, tsconfig.node.json:21

• tsconfig.app.json: Configures TypeScript for the React application source code inside src/. It targets ES2022, includes DOM libraries, and sets jsx to react-jsx. It also defines the paths alias for @/*. If you get type errors related to JSX or browser APIs, check this file.
• tsconfig.node.json: Configures TypeScript for Node.js scripts like vite.config.ts. It targets a more modern ES2023 and includes Node-specific types. Errors in your Vite config file might be caught by the settings here.

Common issues include path alias resolution problems. Ensure that the baseUrl and paths in tsconfig.app.json are consistent with the alias in vite.config.ts.

Sources: tsconfig.app.json:2-29, tsconfig.node.json:2-20

Linting

Code linting is handled by ESLint, configured in eslint.config.js. It helps maintain code quality and consistency. If your editor shows persistent warnings or the npm run lint command fails, this configuration is the place to look.

The configuration extends several recommended rule sets:

• js.configs.recommended: Basic JavaScript rules.
• tseslint.configs.recommended: TypeScript-specific rules.
• reactHooks.configs.flat.recommended: Rules for React Hooks.
• reactRefresh.configs.vite: Integration with Vite's Fast Refresh.

The dist directory is ignored. If you have other build artifacts or generated files that shouldn't be linted, they should be added to the globalIgnores.

Sources: eslint.config.js:8-16

Application Feature Issues

This section covers runtime problems related to specific application features.

Exporting to PNG/PDF

Export functionality is managed by src/lib/exportUtils.ts and relies on html-to-image and jspdf.

The process for both PNG and PDF export is similar:

1. Get the canvas DOM element by its ID (rpg-sheet-canvas).
2. Use toPng() to generate a high-resolution dataUrl of the element.
3. For PNG, create a link and trigger a download.
4. For PDF, create a new jsPDF instance, calculate image dimensions to fit an A4 page, add the image, and save the PDF.

This diagram shows the sequence of events when a user exports a sheet as a PDF.
Sources: src/lib/exportUtils.ts:19-35, src/components/layout/TopBar.tsx:48-51

Common Problems:

• Export fails or image is blank: The document.getElementById("rpg-sheet-canvas") call might be failing. Ensure the Canvas component is rendered and has the correct id.
• Low-quality export: The pixelRatio: 2 option is crucial for quality. If it's removed, the output will be blurry.
• Errors in console: Check the console for errors from html-to-image or jspdf. This could be due to complex CSS, external images causing CORS issues, or unsupported styles. The filter function in exportUtils.ts is designed to exclude problematic elements but is not currently used.

Sources: src/lib/exportUtils.ts:4-5, 22-23, src/components/sheet/Canvas.tsx:30

State Persistence

The application state, including all blocks and their positions, is managed by Zustand. The store is configured to persist data to localStorage.

// src/store/useSheetStore.ts
export const useSheetStore = create<SheetState>()(
  persist(
    (set) => ({
      // ... state and actions
    }),
    { name: "rpg-sheet-storage" } // AutoSave in localStorage
  )
);

If your changes are lost on page refresh, check the browser's developer tools:

1. Go to the "Application" tab.
2. Under "Storage" -> "Local Storage", find the entry with the key rpg-sheet-storage.
3. Verify that its value is being updated as you make changes to the character sheet. If it's not updating, there might be an issue with a Zustand action or the persist middleware.

Sources: src/store/useSheetStore.ts:100-103

Block Rendering and Styling

If a block type appears as "Unknown Block Type" or styles are not applied correctly, the issue is likely in BlockRenderer.tsx.

• Unknown Block Type: This message appears when the block.type does not match any of the if conditions in the renderer. Check the type being passed when the block is created (e.g., in ToolsSidebar.tsx).
• Styling Issues: Block styling is derived from the currently active theme, defined in src/lib/themes.ts. The BlockRenderer component retrieves the current theme's class strings and applies them using cn(). If a style is incorrect, trace it back from the BlockRenderer to the theme definition in THEMES. For example, a header block with level: 1 gets its styles from currentTheme.blocks.header.h1.

Sources: src/components/sheet/BlockRenderer.tsx:16-32, 203-204, src/lib/themes.ts:25-28, src/components/layout/ToolsSidebar.tsx:125-126