Files
dotcom-arcade/docs/12-reference/external-dependencies.md
T

26 KiB

External Dependencies Reference

This document provides a comprehensive reference for all external npm packages used across the Flashpoint Web monorepo, including their purposes, licenses, and alternatives considered.

Table of Contents


Backend Dependencies

Production Dependencies

axios (^1.13.2)

Purpose: HTTP client for making external requests to CDN fallbacks and Flashpoint update servers.

License: MIT

Usage:

  • External CDN fallback requests
  • Flashpoint metadata update checks
  • Community playlist synchronization

Alternatives Considered:

  • node-fetch - Chose axios for better error handling and interceptors
  • got - Chose axios for familiarity and community support

Documentation: https://axios-http.com/


bcrypt (^6.0.0)

Purpose: Password hashing library for secure password storage.

License: MIT

Usage:

  • Hash passwords during user registration
  • Verify passwords during login
  • Cost factor: 10 (2^10 = 1024 rounds)

Alternatives Considered:

  • argon2 - More modern but requires native compilation
  • scrypt - Chose bcrypt for better ecosystem support

Security Notes:

  • Industry-standard password hashing
  • Automatically salts passwords
  • Resistant to rainbow table attacks

Documentation: https://github.com/kelektiv/node.bcrypt.js


better-sqlite3 (^12.6.0)

Purpose: Synchronous SQLite database driver for Node.js.

License: MIT

Usage:

  • Database access for flashpoint.sqlite (read-only)
  • Database access for user.db (read-write)
  • Prepared statements for security
  • Transactions for data consistency

Alternatives Considered:

  • sqlite3 (async) - Chose better-sqlite3 for better performance with synchronous operations
  • sql.js - Chose better-sqlite3 for native performance

Performance Benefits:

  • Faster than async wrappers for read-heavy workloads
  • No callback/promise overhead
  • Better suited for SQLite's architecture

Documentation: https://github.com/WiseLibs/better-sqlite3


cheerio (^1.1.2)

Purpose: Server-side HTML parsing and manipulation library (jQuery-like API).

License: MIT

Usage:

  • Parse HTML responses from external CDN
  • Extract metadata from game pages
  • HTML polyfill injection for legacy games

Alternatives Considered:

  • jsdom - Chose cheerio for lighter weight and faster parsing
  • node-html-parser - Chose cheerio for jQuery-like API familiarity

Documentation: https://cheerio.js.org/


compression (^1.7.4)

Purpose: Express middleware for gzip/deflate compression of HTTP responses.

License: MIT

Usage:

  • Compress API responses
  • Reduce bandwidth usage
  • Improve API performance

Configuration:

  • Threshold: 1KB minimum
  • Compression level: 6 (default)

Documentation: https://github.com/expressjs/compression


cors (^2.8.5)

Purpose: Express middleware for enabling Cross-Origin Resource Sharing.

License: MIT

Usage:

  • Allow frontend origin to access backend API
  • Configure allowed origins, methods, headers
  • Enable credentials for cookie/auth support

Configuration:

{
  origin: process.env.DOMAIN,
  credentials: true,
  optionsSuccessStatus: 200
}

Documentation: https://github.com/expressjs/cors


dotenv (^16.4.5)

Purpose: Load environment variables from .env files.

License: BSD-2-Clause

Usage:

  • Load configuration from .env files
  • Separate configuration from code
  • Environment-specific settings

Best Practices:

  • Never commit .env to version control
  • Use .env.example as template
  • Validate required variables at startup

Documentation: https://github.com/motdotla/dotenv


express (^4.18.3)

Purpose: Fast, unopinionated web framework for Node.js.

License: MIT

Usage:

  • HTTP server and routing
  • Middleware pipeline
  • API endpoint handling
  • Request/response processing

Alternatives Considered:

  • fastify - Chose Express for ecosystem maturity
  • koa - Chose Express for middleware compatibility
  • hapi - Chose Express for simplicity

Documentation: https://expressjs.com/


express-rate-limit (^7.1.5)

Purpose: Rate limiting middleware for Express.

License: MIT

Usage:

  • Prevent brute-force attacks on login endpoint
  • API abuse prevention
  • Fair resource allocation

Configuration:

  • Login: 5 requests per 15 minutes per IP
  • API: 100 requests per 15 minutes per IP

Documentation: https://github.com/express-rate-limit/express-rate-limit


helmet (^7.1.0)

Purpose: Security middleware setting various HTTP headers.

License: MIT

Usage:

  • Set Content-Security-Policy headers
  • Enable HSTS (HTTP Strict Transport Security)
  • Prevent clickjacking with X-Frame-Options
  • XSS protection headers

Headers Set:

  • Content-Security-Policy
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • Strict-Transport-Security

Documentation: https://helmetjs.github.io/


http-proxy-middleware (^2.0.6)

Purpose: Proxy middleware for delegating requests to other servers.

License: MIT

Usage:

  • Proxy game file requests to game-service
  • Proxy legacy content requests
  • Request transformation

Configuration:

  • Target: Game-service URLs
  • Path rewriting
  • Error handling

Documentation: https://github.com/chimurai/http-proxy-middleware


jsonwebtoken (^9.0.3)

Purpose: JSON Web Token (JWT) implementation for authentication.

License: MIT

Usage:

  • Generate access tokens
  • Verify and decode tokens
  • Token expiration handling

Configuration:

  • Algorithm: HS256 (HMAC SHA-256)
  • Expiration: 1 hour (default)
  • Secret: Environment variable

Security Notes:

  • Use strong secret (32+ characters)
  • Validate signature on every request
  • Check expiration before use

Documentation: https://github.com/auth0/node-jsonwebtoken


node-stream-zip (^1.15.0)

Purpose: Read ZIP files without extracting to disk.

License: MIT

Usage:

  • Mount game ZIP archives
  • Stream files from ZIPs
  • List ZIP contents
  • No extraction required

Benefits:

  • No disk space for extraction
  • Faster game loading
  • Reduced I/O operations

Documentation: https://github.com/antelle/node-stream-zip


redis (^4.6.13)

Purpose: Redis client for caching and session storage (optional).

License: MIT

Usage:

  • Cache game metadata queries
  • Distributed rate limiting
  • Session storage

Note: Currently optional, not required for basic operation.

Documentation: https://github.com/redis/node-redis


winston (^3.11.0)

Purpose: Logging library with multiple transports.

License: MIT

Usage:

  • Application logging
  • Error logging
  • Access logs
  • Multiple log levels (error, warn, info, debug)

Configuration:

  • Console transport for development
  • File transport for production
  • Configurable log levels

Documentation: https://github.com/winstonjs/winston


zod (^3.22.4)

Purpose: TypeScript-first schema validation library.

License: MIT

Usage:

  • API request validation
  • Configuration validation
  • Type-safe data parsing

Benefits:

  • TypeScript integration
  • Runtime validation
  • Detailed error messages

Alternatives Considered:

  • joi - Chose Zod for TypeScript-first approach
  • yup - Chose Zod for better TypeScript support

Documentation: https://zod.dev/


Development Dependencies

@types/* packages

Purpose: TypeScript type definitions for JavaScript libraries.

License: MIT

Packages:

  • @types/bcrypt
  • @types/better-sqlite3
  • @types/compression
  • @types/cors
  • @types/express
  • @types/jsonwebtoken
  • @types/node

Documentation: https://github.com/DefinitelyTyped/DefinitelyTyped


@typescript-eslint/* (^7.1.1)

Purpose: TypeScript linting and parser for ESLint.

License: MIT

Packages:

  • @typescript-eslint/eslint-plugin - TypeScript-specific rules
  • @typescript-eslint/parser - TypeScript parser for ESLint

Documentation: https://typescript-eslint.io/


concurrently (^8.2.2)

Purpose: Run multiple npm scripts concurrently with colored output.

License: MIT

Usage:

  • Start all services in development
  • Colored output per service
  • Process management

Documentation: https://github.com/open-cli-tools/concurrently


eslint (^8.57.0)

Purpose: JavaScript and TypeScript linting utility.

License: MIT

Usage:

  • Enforce code quality rules
  • Catch common errors
  • Maintain code consistency

Documentation: https://eslint.org/


tsx (^4.7.1)

Purpose: TypeScript runner with watch mode.

License: MIT

Usage:

  • Run TypeScript files without compilation
  • Watch mode for development
  • Fast esbuild-based compilation

Documentation: https://github.com/esbuild-kit/tsx


typescript (^5.4.2)

Purpose: TypeScript language and compiler.

License: Apache-2.0

Usage:

  • Type checking
  • Transpilation to JavaScript
  • IDE integration

Configuration: tsconfig.json

Documentation: https://www.typescriptlang.org/


vitest (^1.3.1)

Purpose: Fast unit test framework powered by Vite.

License: MIT

Usage:

  • Unit testing
  • Integration testing
  • Test coverage

Features:

  • Vite-powered
  • Jest-compatible API
  • TypeScript support

Documentation: https://vitest.dev/


Frontend Dependencies

Production Dependencies

@hookform/resolvers (^5.2.2)

Purpose: Validation resolvers for React Hook Form.

License: MIT

Usage:

  • Zod validation integration
  • Form schema validation
  • Type-safe form validation

Documentation: https://github.com/react-hook-form/resolvers


@radix-ui/react-* (various versions)

Purpose: Unstyled, accessible UI component primitives.

License: MIT

Components:

  • react-alert-dialog - Modal dialogs
  • react-avatar - User avatars
  • react-checkbox - Checkboxes
  • react-dialog - Dialogs
  • react-dropdown-menu - Dropdown menus
  • react-label - Form labels
  • react-popover - Popovers
  • react-scroll-area - Custom scrollbars
  • react-select - Select inputs
  • react-separator - Visual separators
  • react-slot - Component composition
  • react-switch - Toggle switches
  • react-toast - Toast notifications
  • react-toggle - Toggle buttons
  • react-tooltip - Tooltips

Benefits:

  • Full keyboard navigation
  • Screen reader support
  • Focus management
  • Unstyled (style with Tailwind)

Documentation: https://www.radix-ui.com/


@ruffle-rs/ruffle (^0.2.0-nightly.2026.1.9)

Purpose: Flash Player emulator compiled to WebAssembly.

License: MIT / Apache-2.0 (dual license)

Usage:

  • Play Flash (SWF) games in browser
  • No plugin required
  • WebAssembly-based emulation

Integration:

  • Files copied to public/ruffle/ on install
  • Loaded dynamically in GamePlayer component
  • Supports ActionScript 1, 2, and partial 3

Documentation: https://ruffle.rs/


@tanstack/react-query (^5.28.9)

Purpose: Data synchronization and caching library.

License: MIT

Usage:

  • Fetch and cache game data
  • Automatic background refetching
  • Optimistic updates
  • Pagination support

Configuration:

  • Stale time: 5 minutes
  • Cache time: 10 minutes
  • Retry: 3 attempts

Alternatives Considered:

  • swr - Chose React Query for more features
  • rtk-query - Chose React Query for flexibility

Documentation: https://tanstack.com/query/latest


@tanstack/react-table (^8.21.3)

Purpose: Headless table library for building data tables.

License: MIT

Usage:

  • Game list tables
  • User management tables
  • Sorting and filtering
  • Pagination

Documentation: https://tanstack.com/table/latest


@tanstack/react-virtual (^3.2.0)

Purpose: Headless virtualization library for large lists.

License: MIT

Usage:

  • Virtualize game lists
  • Handle thousands of games efficiently
  • Smooth scrolling performance

Benefits:

  • Constant rendering time
  • Reduced memory usage
  • Dynamic row heights

Documentation: https://tanstack.com/virtual/latest


axios (^1.6.8)

Purpose: HTTP client for API requests.

License: MIT

Usage:

  • API requests to backend
  • Request/response interceptors
  • Automatic token refresh
  • Error handling

Configuration:

  • Base URL: /api
  • Timeout: 30 seconds
  • Auth token injection

Documentation: https://axios-http.com/


class-variance-authority (^0.7.1)

Purpose: Utility for creating component variant styles.

License: MIT

Usage:

  • Define component variants
  • Conditional class names
  • Type-safe variant props

Example:

const button = cva('btn', {
  variants: {
    size: { sm: 'text-sm', lg: 'text-lg' },
    color: { primary: 'bg-blue', secondary: 'bg-gray' }
  }
});

Documentation: https://cva.style/docs


clsx (^2.1.0)

Purpose: Utility for constructing className strings conditionally.

License: MIT

Usage:

  • Conditional class names
  • Merge class strings
  • Clean syntax

Example:

clsx('btn', { 'btn-active': isActive }, className)

Documentation: https://github.com/lukeed/clsx


cmdk (^1.1.1)

Purpose: Command palette component (Command+K interface).

License: MIT

Usage:

  • Search games with keyboard shortcuts
  • Navigation shortcuts
  • Accessible command menu

Documentation: https://cmdk.paco.me/


date-fns (^3.6.0)

Purpose: Modern JavaScript date utility library.

License: MIT

Usage:

  • Format timestamps
  • Calculate durations
  • Parse dates
  • Relative time formatting

Alternatives Considered:

  • moment - Chose date-fns for tree-shaking and smaller size
  • dayjs - Chose date-fns for better TypeScript support

Documentation: https://date-fns.org/


lucide-react (^0.358.0)

Purpose: Icon library for React.

License: ISC

Usage:

  • UI icons throughout application
  • Consistent icon system
  • Fully customizable

Benefits:

  • Tree-shakeable
  • TypeScript support
  • Large icon collection

Documentation: https://lucide.dev/


next-themes (^0.4.6)

Purpose: Theme management for Next.js and React apps.

License: MIT

Usage:

  • Dark/light mode support
  • System theme detection
  • Theme persistence
  • No flash on load

Note: Despite the name, works with any React app, not just Next.js.

Documentation: https://github.com/pacocoursey/next-themes


react (^18.3.1)

Purpose: JavaScript library for building user interfaces.

License: MIT

Usage:

  • Component-based UI development
  • Virtual DOM for performance
  • Hooks for state management

Documentation: https://react.dev/


react-dom (^18.3.1)

Purpose: React package for working with the DOM.

License: MIT

Usage:

  • Render React components to DOM
  • Event system
  • Portal support

Documentation: https://react.dev/


react-hook-form (^7.71.1)

Purpose: Performant form library for React.

License: MIT

Usage:

  • Login/registration forms
  • Settings forms
  • Form validation
  • Integration with Zod

Benefits:

  • Minimal re-renders
  • Easy validation
  • TypeScript support

Alternatives Considered:

  • formik - Chose React Hook Form for better performance

Documentation: https://react-hook-form.com/


react-router-dom (^6.22.3)

Purpose: Declarative routing for React applications.

License: MIT

Usage:

  • Client-side routing
  • URL state management
  • Nested routes
  • Route protection

Features:

  • Data loading
  • Code splitting
  • Navigation guards

Documentation: https://reactrouter.com/


recharts (^3.6.0)

Purpose: Composable charting library built on React components.

License: MIT

Usage:

  • Play statistics charts
  • Activity graphs
  • Platform distribution charts

Chart Types:

  • Line charts for activity over time
  • Bar charts for comparisons
  • Pie charts for distributions

Documentation: https://recharts.org/


sonner (^2.0.7)

Purpose: Opinionated toast notification library for React.

License: MIT

Usage:

  • Success/error notifications
  • Loading states
  • Action toasts
  • Accessible notifications

Features:

  • Beautiful defaults
  • Keyboard dismissal
  • Promise-based API

Documentation: https://sonner.emilkowal.ski/


tailwind-merge (^3.4.0)

Purpose: Utility for merging Tailwind CSS classes without conflicts.

License: MIT

Usage:

  • Merge component class names
  • Resolve Tailwind conflicts
  • Clean className composition

Example:

twMerge('p-4 text-red-500', 'p-2') // => 'p-2 text-red-500'

Documentation: https://github.com/dcastil/tailwind-merge


tailwindcss-animate (^1.0.7)

Purpose: Tailwind CSS plugin for animations.

License: MIT

Usage:

  • Pre-built animation utilities
  • Keyframe animations
  • Transition utilities

Animations:

  • Fade in/out
  • Slide in/out
  • Scale
  • Spin

Documentation: https://github.com/jamiebuilds/tailwindcss-animate


zod (^4.3.5)

Purpose: TypeScript-first schema validation.

License: MIT

Usage:

  • Form validation
  • API response validation
  • Type-safe data parsing

Documentation: https://zod.dev/


zustand (^4.5.2)

Purpose: Small, fast state management library.

License: MIT

Usage:

  • Authentication state
  • Theme preferences
  • UI state (sidebar, view mode)

Benefits:

  • No boilerplate
  • Direct state mutation
  • Built-in persistence
  • TypeScript support

Alternatives Considered:

  • redux - Chose Zustand for simplicity
  • jotai - Chose Zustand for familiarity

Documentation: https://zustand-demo.pmnd.rs/


Frontend Development Dependencies

@types/react (^18.2.66)

Purpose: TypeScript type definitions for React.

License: MIT

Documentation: https://github.com/DefinitelyTyped/DefinitelyTyped


@types/react-dom (^18.2.22)

Purpose: TypeScript type definitions for React DOM.

License: MIT

Documentation: https://github.com/DefinitelyTyped/DefinitelyTyped


@vitejs/plugin-react (^4.2.1)

Purpose: Official Vite plugin for React.

License: MIT

Usage:

  • React Fast Refresh
  • JSX transformation
  • React DevTools support

Documentation: https://github.com/vitejs/vite-plugin-react


autoprefixer (^10.4.19)

Purpose: PostCSS plugin to add vendor prefixes automatically.

License: MIT

Usage:

  • Automatic CSS vendor prefixes
  • Browser compatibility
  • Works with Tailwind CSS

Documentation: https://github.com/postcss/autoprefixer


postcss (^8.4.38)

Purpose: Tool for transforming CSS with JavaScript plugins.

License: MIT

Usage:

  • Tailwind CSS processing
  • Autoprefixer
  • CSS optimization

Documentation: https://postcss.org/


shx (^0.3.4)

Purpose: Cross-platform shell commands for npm scripts.

License: MIT

Usage:

  • Copy Ruffle files to public/
  • Cross-platform file operations
  • npm script compatibility

Commands Used:

  • mkdir -p - Create directories
  • cp -r - Copy files recursively

Documentation: https://github.com/shelljs/shx


tailwindcss (^3.4.1)

Purpose: Utility-first CSS framework.

License: MIT

Usage:

  • Styling system
  • Responsive design
  • Dark mode
  • Custom theme

Configuration: tailwind.config.js

Documentation: https://tailwindcss.com/


typescript (^5.4.2)

Purpose: TypeScript language and compiler.

License: Apache-2.0

Usage:

  • Type checking
  • Transpilation
  • IDE integration

Documentation: https://www.typescriptlang.org/


vite (^5.2.0)

Purpose: Next-generation frontend build tool.

License: MIT

Usage:

  • Development server with HMR
  • Production builds
  • Code splitting
  • Asset optimization

Benefits:

  • Instant server start
  • Lightning-fast HMR
  • Optimized builds
  • Plugin ecosystem

Alternatives Considered:

  • webpack - Chose Vite for speed
  • parcel - Chose Vite for better control

Documentation: https://vitejs.dev/


vite-plugin-static-copy (^3.1.4)

Purpose: Vite plugin for copying static assets to build output.

License: MIT

Usage:

  • Copy Ruffle files to dist/
  • Copy public assets
  • Build-time file copying

Documentation: https://github.com/sapphi-red/vite-plugin-static-copy


Game Service Dependencies

Production Dependencies

axios (^1.6.8)

Purpose: HTTP client for CDN fallback requests.

License: MIT

Usage:

  • Fetch files from external CDN
  • Cache downloaded content
  • Error handling

Documentation: https://axios-http.com/


cors (^2.8.5)

Purpose: Enable CORS for cross-domain game content.

License: MIT

Usage:

  • Allow all origins (required for game content)
  • Enable CORS headers
  • Preflight request handling

Documentation: https://github.com/expressjs/cors


dotenv (^16.4.5)

Purpose: Load environment variables.

License: BSD-2-Clause

Usage:

  • Configuration management
  • Environment-specific settings

Documentation: https://github.com/motdotla/dotenv


express (^4.18.3)

Purpose: Web framework for HTTP servers.

License: MIT

Usage:

  • Proxy server (port 22500)
  • GameZip server (port 22501)
  • Middleware pipeline
  • Request routing

Documentation: https://expressjs.com/


node-stream-zip (^1.15.0)

Purpose: Stream files from ZIP archives without extraction.

License: MIT

Usage:

  • Mount game ZIP archives
  • Stream individual files
  • List ZIP contents
  • No disk extraction required

Benefits:

  • Instant access to ZIP contents
  • No disk space for extraction
  • Reduced I/O operations

Documentation: https://github.com/antelle/node-stream-zip


winston (^3.11.0)

Purpose: Logging library.

License: MIT

Usage:

  • Request logging
  • Error logging
  • Debug logging
  • Configurable log levels

Documentation: https://github.com/winstonjs/winston


Game Service Development Dependencies

@types/cors (^2.8.17)

Purpose: TypeScript definitions for cors.

License: MIT

Documentation: https://github.com/DefinitelyTyped/DefinitelyTyped


@types/express (^4.17.21)

Purpose: TypeScript definitions for Express.

License: MIT

Documentation: https://github.com/DefinitelyTyped/DefinitelyTyped


@types/node (^20.11.19)

Purpose: TypeScript definitions for Node.js.

License: MIT

Documentation: https://github.com/DefinitelyTyped/DefinitelyTyped


tsx (^4.7.1)

Purpose: TypeScript runner for development.

License: MIT

Usage:

  • Development server with watch mode
  • Fast compilation

Documentation: https://github.com/esbuild-kit/tsx


typescript (^5.3.3)

Purpose: TypeScript compiler.

License: Apache-2.0

Usage:

  • Type checking
  • Compilation to JavaScript

Documentation: https://www.typescriptlang.org/


Shared Development Dependencies

Root-Level Dependencies

These dependencies are used for managing the monorepo and running all services.

concurrently (^8.2.2)

Purpose: Run multiple services concurrently.

License: MIT

Usage:

  • Start all services in development
  • Colored output per service

Documentation: https://github.com/open-cli-tools/concurrently


License Summary

License Distribution

License Count Packages
MIT ~95% Most packages
Apache-2.0 ~3% TypeScript, some Ruffle components
ISC ~1% lucide-react
BSD-2-Clause ~1% dotenv

License Compatibility

All dependencies use permissive open-source licenses compatible with commercial and private use:

  • MIT: Permissive, allows commercial use, modification, distribution
  • Apache-2.0: Permissive, includes patent grant
  • ISC: Permissive, similar to MIT
  • BSD-2-Clause: Permissive, requires attribution

No copyleft licenses (GPL, LGPL, AGPL) are used, ensuring maximum flexibility for deployment and modification.


Dependency Management Best Practices

Version Pinning

  • Production: Use caret ranges (^) for automatic minor/patch updates
  • Critical: Pin exact versions for security-sensitive packages (bcrypt, jsonwebtoken)
  • Review: Regularly review and update dependencies

Security Audits

Run security audits regularly:

# Check for vulnerabilities
npm audit

# Fix automatically (careful with breaking changes)
npm audit fix

# Update dependencies
npm update

Bundle Size Monitoring

Monitor frontend bundle size:

# Analyze bundle
npm run build -- --analyze

# Check bundle size
ls -lh frontend/dist/assets/*.js

Target: Keep main bundle under 500KB gzipped.


Alternative Considerations

Considered but Not Used

State Management

  • Redux Toolkit: Too much boilerplate for project size
  • MobX: Less TypeScript-friendly than Zustand
  • Recoil: Still experimental, less mature ecosystem

UI Components

  • Material-UI: Too opinionated, larger bundle size
  • Ant Design: Less customizable than Radix + Tailwind
  • Chakra UI: Chose Tailwind for more control

Database

  • PostgreSQL: Overkill for project scale, requires separate server
  • MySQL: Same as PostgreSQL
  • MongoDB: Not suitable for relational data structure

ORM/Query Builder

  • Prisma: Adds complexity, better-sqlite3 is sufficient
  • TypeORM: Too heavy for SQLite use case
  • Knex.js: Unnecessary for prepared statement approach

Updating Dependencies

Update Process

  1. Check for updates:

    npm outdated
    
  2. Review changelogs for breaking changes

  3. Update one service at a time:

    cd backend
    npm update
    npm test
    
  4. Test thoroughly before updating other services

  5. Commit updates with clear messages:

    git commit -m "chore(backend): update dependencies"
    

Major Version Updates

For major version updates:

  1. Read migration guide
  2. Update TypeScript types
  3. Fix breaking changes
  4. Run full test suite
  5. Test in production-like environment