Directory structure en US - rocambille/start-express-react GitHub Wiki

The default structure of a StartER application is a starting point. You are free to organize your application however you like. StartER imposes no constraints on the location of an element, as long as you adapt the code to your organization: you have control!

.
├── .env
├── .env.sample
├── compose.yaml
├── compose.prod.yaml
├── Dockerfile
├── index.html
├── server.ts
└── src
    ├── database
    │   └── schema.sql
    ├── express
    │   ├── routes.ts
    │   └── modules
    │       └── ...
    ├── react
    │   ├── routes.tsx
    │   └── components
    │       └── ...
    └── types
        └── index.d.ts

You can use the make:clone script provided with StartER to duplicate this structure and create new modules or components. This script does not impose any opinionated templates; it allows you to replicate your own structures and best practices.

StartER uses a .env file to separate environment variables from code. During a fresh installation of StartER, your application's root directory will contain a .env.sample file that defines common environment variables. This file serves as a common template for sharing necessary variables without exposing sensitive information. After installing StartER, copy this .env.sample file as .env.

cp .env.sample .env

Here are the required variables that you must fill in with your own values:

StartER allows an additional variable APP_PORT to specify server port (5173 by default).

The MySQL Docker image allows additional variables such as MYSQL_USER, MYSQL_PASSWORD, or MYSQL_RANDOM_ROOT_PASSWORD. Refer to the mysql image documentation for more details.

Also in your .env file, you can add:

• additional variables for third-party tools you have installed,
• your own variables.

Keep in mind

• You can include additional variables in your StartER application's .env.sample file. By adding entries to the .env.sample file, other developers on your team can clearly identify the environment variables required to run your StartER application.

• Your .env file should never be added in a Git commit, as each workstation (local machine or server) running your StartER application may require a different environment configuration. Furthermore, this would pose a security risk if intruders accessed your repository, as your sensitive credentials would be exposed.

To start your application, StartER uses tsx (which uses the node command under the hood) with the --env-file option to load your .env file. Your variables are then available in process.env.

// Get variables from .env file for database connection
const { MYSQL_ROOT_PASSWORD, MYSQL_DATABASE } = process.env;

You can edit the tsx command options in the scripts in the package.json file at the root of the project.

{
  "scripts": {
  "dev": "tsx --env-file=.env server",
  "start": "tsx --env-file=.env server",
    ...
  },
  ...
}

For example, you can pass multiple --env-file arguments to build a more complex configuration with multiple .env files (.env.local, .env.prod, etc.). Refer to the --env-file documentation for more details.

According to the official documentation:

Docker provides the ability to package and run an application in a loosely isolated environment called a container.
[...] A container is a runnable instance of an image.
[...] To build your own image, you create a Dockerfile with a simple syntax for defining the steps needed to create the image and run it.

A Dockerfile defines the contents and startup behavior of a single container. A StartER application image is based on an Alpine Linux image with the latest LTS version of Node.js pre-installed.

ARG NODE_VERSION=22.14.0

FROM node:${NODE_VERSION}-alpine

The Dockerfile copies your StartER application sources into this image, installs dependencies, and runs the npm run dev command.

COPY . .

# Run the application.
CMD ["npm", "run", "dev"]

The .dockerignore file excludes files not needed to build the image (such as README, LICENSE...).

Additionally, a compose.yaml file allows you to define a multi-container application. In an isolated network, the StartER compose.yaml file defines:

• a server container for your StartER application,
• a database container to provide a MySQL server for your application,
• an adminer container to provide a graphical database management interface with Adminer.

To create and start the containers in development mode, run the command:

docker compose up --build

More options are available in the docker compose up documentation.

The compose.prod.yaml file specializes the containers for production:

• The NODE_ENV environment variable is set to production.
• The server container is started with npm run build && npm run start, rather than npm run dev.
• The adminer container is not provided.

To create and start the containers in production mode, run the command:

docker compose -f compose.prod.yaml up --build

The index.html file references entry-client and includes a <!--ssr-outlet--> tag where the server-rendered markup is injected (see explanation about the "one server" of StartER for advanced details).

Also, the index.html file is the anchor point for Pico CSS by linking the library and adjusting some basic variables.

<!DOCTYPE html>
<html lang="fr">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Start Express React</title>
    <link
      rel="shortcut icon"
      href="/src/react/assets/images/favicon.png"
      type="image/png"
    />
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css"
    />
    <style>
      :root {
        --pico-border-radius: 2rem;
        --pico-form-element-spacing-vertical: 0.5rem;
        --pico-form-element-spacing-horizontal: 1rem;
      }
    </style>
  </head>
  <body>
    <div class="container" id="root"><!--ssr-outlet--></div>
    <script type="module" src="/src/entry-client"></script>
  </body>
</html>

Refer to the Pico CSS documentation for a list of available variables.

The server.ts file is the entry point to the framework. Its code bridges the gap between an Express server and a Vite server to create one server.

Most of your StartER application is hosted in the src directory. By default, the src directory contains the following directories:

• database,
• express,
• react,
• types.

The express and react directories are explained in more detail on their respective pages, but think of them as the heart of your StartER application. The express directory contains all your backend routes, while the react directory contains all your frontend routes.

The database directory contains your database schema as well as a client declaration to connect to the "database" service in your StartER application's Docker network.

The types directory contains the TypeScript type definitions shared throughout your StartER application.

These directories form the basis of your StartER application. To understand their roles and interactions, see the following pages:

• Database
• Express
• React
• Types