Structure

There are quite a few files and folders in the base structure of this starter kit, which can make it initially confusing. If all you want to do is start creating your app, you can:

• Write your React components in web/src/, just as you would in a Create React App application's src/ directory; and
• Write your Express routes in api/api.js (or in sub-routers that you .use here);
  • Endpoints are all mounted at /api and can be accessed relatively, so if you defined router.get("/endpoint", ...) the client would fetch("/api/endpoint"));
  • Dependencies that are used by the server at runtime must be installed as production dependencies.

For more detail, see below.

• .github - files for configuring the GitHub repo, e.g. providing templates for issues and pull requests

• .vscode - files for configuring the VS Code IDE, including defining some useful snippets and providing debugging configuration for the dev mode

• api/

  • migrations/ - migrations for keeping database versions in sync, using pg-node-migrate

  • static/ - contains the outputs of the client-side Vite build

  • utils/ - contains various utility modules. In practice, you'll probably:

    • Import from and maybe add new options to config.cjs;
    • Import from logger.js; and
    • Ignore middleware.js entirely (all predefined middleware is already used in app.js).

    See api/utils/README.md for more details.

  • api.js - the crucial file in the server directory, where the Express router that defines the API routes is created. To facilicate push-state routing (the React Router client-side pages) in production mode, all API routes are mounted at /api, so router.get("/", ...) defines the handler for GET /api. Other methods and routes can be added here, all relative to that top-level /api endpoint.

  • app.js - creates and configures an Express application object with appropriate middleware, including mounting the router described above and serving the client files for production mode

  • db.js - this exposes functions that allow the server to connect to and disconnect from the database, as well as an object with a query method you can import and use where you want to access the database. The connection string is supplied as the DATABASE_URL (see Dev Setup#Databases).

  • server.js - imports and starts the app on the configured port (either the value of the PORT environment variable or the default, 3000)

• e2e/ - files for the Playwright end-to-end tests

• web/

  • public/ - files that should be served at the root of the web server (e.g. robots.txt or favicon.ico could go here)
  • src/
    • components/ - low-level components that may appear on multiple pages
    • pages/ - contains the React components representing different pages within the site, currently just About.js and Home.js
    • services/ - services for communicating with the backend API
    • App.jsx - this is the root component of the app, where the React Router switch that chooses between the pages can be found; new page routes can be added here
    • index.jsx - mounts the root component in a router context and renders it in the DOM.
  • vite.config.js - Vite configuration for building the client-side app in development and production modes