⚙️ Environment

Overview

The expresso-macchiato starter relies on environment variables to configure core aspects of the application. These values must be injected using Node's standard process.env, and they are typically defined in a .env file at the root of your project.

Environment configuration is handled via the dotenv package, storing the values in an object that will be passed inside the Starter. In the generated project (npx create-expresso-macchiato), this setup is preconfigured automatically.

How it works

Inside your project’s entry point, dotenv.config() is called before reading values from process.env. Here's an example configuration object:

tsCopiaModificaimport { config } from 'dotenv';
import { ProjectConfigs } from 'expresso-macchiato';
import { MyProjectConfig } from './types/generic.types';

config();

export const projectConfig: ProjectConfigs & MyProjectConfig = {
    SERVER_PORT: parseInt(process.env.SERVER_PORT ?? '3000'),
    API_URL: process.env['API_URL'],
    ERROR_FILE_PATH: process.env['ERROR_FILE_PATH'],

    DB_DIALECT: process.env.DB_DIALECT,
    DB_NAME: process.env.DB_NAME,
    DB_HOST: process.env.DB_HOST,
    DB_PORT: parseInt(process.env.DB_PORT ?? '5432'),
    DB_USER: process.env.DB_USER,
    DB_PASSWORD: process.env.DB_PASSWORD,

    MINIO_ENDPOINT: process.env['MINIO_ENDPOINT'] ?? '12.0.0.7',
    MINIO_PORT: parseInt(process.env['MINIO_PORT'] ?? '9000'),
    MINIO_SSL: process.env['MINIO_SSL'] === 'true',
    MINIO_ACCESS_KEY: process.env['MINIO_ACCESS_KEY'],
    MINIO_SECRET_KEY: process.env['MINIO_SECRET_KEY'],
};

🔐 Sensitive values like passwords and access keys must never be hardcoded directly into the codebase.

If you need the token authentication, the secret key is gonna be passed in the Starter constructor (use the process.env["TOKEN_KEY"])

Template env file

SERVER_PORT=3000 # required
API_URL="http://127.0.0.1:3000/api" # not required
ERROR_FILE_PATH="logs/errors.log" # not required
TOKEN_KEY="your-ultra-secret-key" # required if you want to use tokens

# ---
# Db parameters are required depending on the DB_DIALECT (check typeorm requirements)
# Use the next lines how you want, the template comes from a configuration for a sqlite3 db.
# ---
# DB_DIALECT="postgres"
# DB_HOST="127.0.0.1"
# DB_PORT=5432
# DB_USER="username"
# DB_PASSWORD="mystrongbdpassword"
# DB_NAME="expresso"

DB_DIALECT="sqlite"
DB_NAME="db/expresso.db"



# Not for the expresso-macchiato package but inside the template because i often use it.
MINIO_ENDPOINT="127.0.0.1"
MINIO_PORT=9000
MINIO_SSL=false
MINIO_ACCESS_KEY="accesskey"
MINIO_SECRET_KEY="secretkey"

SERVER_PORT

Type: number Required: ✅ Example: 3000

Defines the port on which the Express server will listen. If omitted, the server defaults to port 3000.

API_URL

Type: string Required: ❌ (conditionally required based on setup) Example: http://127.0.0.1:3000/api

This variable defines the base URL for your backend API.

If the client option is specified in the expresso-macchiato starter, the value of API_URL will be automatically exposed at the endpoint /apiUrl, returning it as plain text. This is especially useful for Single Page Applications (SPAs) that need to dynamically determine the backend base URL at runtime (e.g., for axios requests).

Usage Notes:

  • Leave undefined in production if the client is served from the same origin as the backend.

  • Set explicitly if the frontend is hosted elsewhere or for local development purposes.

ERROR_FILE_PATH

Type: string Required: ❌ Example: logs/errors.log

This variable is not read directly by the starter but by the external logging package utils-logger-av.

If set, it enables log-to-file functionality by specifying the path where logs should be written. If not set, logs will not be persisted to file, and only console output will be used.

TOKEN_KEY

Type: string Required: ❌ (conditionally required) Example: your-ultra-secret-key

This key is used to sign and verify tokens in authentication flows. It is only necessary if your application enables token-based authentication (e.g., JWT).

If you configure token auth manually, TOKEN_KEY must be provided to ensure secure operations.

Database Configuration

The following environment variables define the connection settings for your database and follow the standard format used by ORMs like TypeORM. These values will be parsed at runtime and are required if you're using any SQL database other than the default sqlite configuration.

envCopiaModifica# DB_DIALECT="postgres"
# DB_HOST="127.0.0.1"
# DB_PORT=5432
# DB_USER="username"
# DB_PASSWORD="mydbpassword"
# DB_NAME="expresso"

Variable Details:

Variable
Description
Example

DB_DIALECT

The SQL dialect (e.g., postgres, mysql)

postgres

DB_HOST

Database host (IP or domain)

127.0.0.1

DB_PORT

Database port

5432

DB_USER

Username to authenticate

username

DB_PASSWORD

Password to authenticate

mydbpassword

DB_NAME

The name of the database

expresso

These variables must be correctly configured to establish a connection to your database engine of choice. The application does not validate these at runtime—misconfiguration may result in runtime connection errors.

💡 If you're using SQLite for rapid development, you can skip these and only define DB_DIALECT and DB_NAME.

MinIO Configuration

This config section is not directly present in the express-o package, but it's present in the epxress-o template of create-express-o

envCopiaModificaMINIO_ENDPOINT="127.0.0.1"
MINIO_PORT=9000
MINIO_SSL=false
MINIO_ACCESS_KEY="your-generated-access-token"
MINIO_SECRET_KEY="your-generated-secret-token"

MinIO is used as an object storage backend. It is thought to be working with the bitnami/minio docker images but again, this is not directly in the express-o package, thos are found in the starter template.

Feel free to customize your template how much you want.

Previousexpresso-macchiatoNextUtilities

Last updated