Skip to main content

Manual installation

Requirements​

  • Node.js v18+
  • Postgres database
  • Typescript - optional, required if creating modules and providers since we need TS decorators
  • Email provider (optional, needed for password reset, email confirmation)

Install Zmaj​

In your Node project, install zmaj by running:

npm install zmaj

To configure app, pass config object to runServer function, or specify .env file in the root of your project.

Passing values directly to runServer​

import { runServer } from "zmaj"

await runServer({
    // keep this key secret
    global: { secretKey: "my_secret_key_min_20_chars" },
    // database params
    database: {
        database: "my_db",
        host: "localhost",
        username: "db_user",
        password: "db_password",
        port: 5432,
    },
    // this wil automatically run migrations that create necessary tables
    migrations: { autoRunMigrations: true },
})

Using env file​

Zmaj will by default look for .env file at project root. If you want to use custom path, pass { config: { envPath: ".env.dev" } } to runServer:

import { runServer } from "zmaj"

await runServer({
    config: { envPath: ".env.dev" },
    migrations: { autoRunMigrations: true },
})

You must provide secret key, and database configuration. Secret key must be at least 20 characters. For configuring using environment variables, look at this pages, or look at the file we use during development.

Migrations​

You must run migrations before starting to use Zmaj, since Zmaj stores it's data in database. You can run them manually by running: npx zmaj migrate. It will ask you to provide a path to .env file, so we know how to connect to the database. You can make Zmaj run migration automatically by passing { migrations: { autoRunMigrations: true } }.

Decorators​

If you are using features that require use of TS decorators, you must have decorators enabled in tsconfig.json.

{
    "compilerOptions": {
        "emitDecoratorMetadata": true,
        "experimentalDecorators": true
    }
}