Prerequisites
Before you begin, ensure you have the following installed:
- Node.js (version 18 or higher recommended)
- npm, yarn, or pnpm package manager
- Git for version control
Installation
Clone the repository
First, clone the Vocab Vault repository to your local machine:git clone <repository-url>
cd vocab-vault-alpha
Install dependencies
Install all required dependencies using your preferred package manager:The postinstall script will automatically run patch-package to apply any necessary patches to dependencies.
Development Server
To start the development server with hot module replacement (HMR):
The development server will start on http://localhost:8080 by default. The server is configured to:
- Listen on all network interfaces (
::)
- Disable the HMR overlay for a cleaner development experience
- Provide fast refresh with SWC compilation
Building for Production
Standard Production Build
Create an optimized production build:
This command:
- Compiles TypeScript and bundles all assets
- Optimizes and minifies code for production
- Outputs to the
dist/ directory
- Generates bundle visualization in
dist/stats.html
- Creates optimized chunks:
vocabulary - Vocabulary data for better cachingvendor - Third-party dependenciesvendor-framer - Framer Motion library (separated due to size)
Development Build
For debugging purposes, you can create a build in development mode:
This build includes source maps and debugging information.
Preview Production Build
To preview the production build locally:
This serves the dist/ directory and allows you to test the production build before deployment.
Code Quality
Linting
Run ESLint to check for code quality issues:
Project Structure
The project uses the following key technologies:
- Vite - Build tool and dev server
- React + TypeScript - UI framework and type safety
- Tailwind CSS - Styling
- SWC - Fast compilation
- Path aliases -
@/ maps to ./src/ for cleaner imports
Troubleshooting
Port Already in Use
If port 8080 is already in use, you can specify a different port:
Dependency Issues
If you encounter dependency issues:
-
Clear node_modules and reinstall:
rm -rf node_modules package-lock.json
npm install
-
Ensure
patch-package runs successfully during installation
Build Errors
- TypeScript errors: Run
npx tsc --noEmit to check for type errors
- Out of memory: Increase Node.js memory limit:
NODE_OPTIONS="--max-old-space-size=4096" npm run build
HMR Not Working
If hot module replacement isn’t working:
- Check that the dev server is running on the expected port
- Try restarting the dev server
- Clear browser cache and reload
Use the bundle visualization at dist/stats.html after production builds to analyze bundle size and optimize your build.