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
    │   │   └── ...
    │   └── pages
    │       └── ...
    └── types
        └── index.d.ts

StartER uses a .env file to separate environment variables from the code. During a fresh installation of StartER, your application's root directory will contain a .env.sample file that defines the current environment variables. After installing StartER, copy this .env.sample file under the name .env.

cp .env.sample .env

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

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 application's .env.sample file. By adding entries to the .env.sample file, other members of your team can clearly identify the environment variables required to run your application.

• Your .env file should never be added in a Git commit, as each workstation (local machine or server) running your application may require a different environment configuration. Furthermore, this would pose a security issue 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 application's sources into this image, installs dependencies, and runs the npm run dev command.

COPY . .

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

Note that the .dockerignore file allows you to ignore files that are not relevant for copying to the image (README, LICENSE, etc.).

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 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 start the application 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 your application 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 start the application 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 One server for advanced details).

In addition, the index.html file is the anchor point for Pico CSS by linking the library and adjusting first 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 for the framework. Its code connects your Express application to a Vite server to create a "one server".

Most of your 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 consider them the heart of your 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 application's Docker network.

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

Refer to the following pages for more details:

• Database
• Express
• React
• Types