- Get Started
- Product
- Resources
- Tools & SDKs
- Framework
- Reference
- Get Started
- Product
- Resources
- Tools & SDKs
- Framework
- Reference
Configure Medusa Backend
In this document, you’ll learn how to create a file service in the Medusa application and the methods you must implement in it.
The configurations for your Medusa application are in medusa-config.ts
located in the root of your Medusa project. The configurations include configurations for database, modules, and more.
medusa-config.ts
exports the value returned by the defineConfig
utility function imported from @medusajs/framework/utils
.
defineConfig
accepts as a parameter an object with the following properties:
- projectConfig (required): An object that holds general configurations related to the Medusa application, such as database or CORS configurations.
- admin: An object that holds admin-related configurations.
- modules: An object that configures the Medusa application's modules.
- featureFlags: An object that enables or disables features guarded by a feature flag.
For example:
Environment Variables#
It's highly recommended to store the values of configurations in environment variables, then reference them within medusa-config.ts
.
During development, you can set your environment variables in the .env
file at the root of your Medusa application project. In production,
setting the environment variables depends on the hosting provider.
projectConfig#
This property holds essential configurations related to the Medusa application, such as database and CORS configurations.
databaseName#
The name of the database to connect to. If the name is specified in databaseUrl
, then you don't have to use this configuration.
Make sure to create the PostgreSQL database before using it. You can check how to create a database in PostgreSQL's documentation.
Example
databaseUrl#
The PostgreSQL connection URL of the database, which is of the following format:
Where:
[user]
: (required) your PostgreSQL username. If not specified, the system's username is used by default. The database user that you use must have create privileges. If you're using thepostgres
superuser, then it should have these privileges by default. Otherwise, make sure to grant your user create privileges. You can learn how to do that in PostgreSQL's documentation.[:password]
: an optional password for the user. When provided, make sure to put:
before the password.[host]
: (required) your PostgreSQL host. When run locally, it should belocalhost
.[:port]
: an optional port that the PostgreSQL server is listening on. By default, it's5432
. When provided, make sure to put:
before the port.[dbname]
: (required) the name of the database.
You can learn more about the connection URL format in PostgreSQL’s documentation.
Example
For example, set the following database URL in your environment variables:
Then, use the value in medusa-config.ts
:
databaseSchema#
The database schema to connect to. This is not required to provide if you’re using the default schema, which is public
.
databaseLogging#
This configuration specifies whether database messages should be logged.
Example
databaseDriverOptions#
This configuration is used to pass additional options to the database connection. You can pass any configuration. For example, pass the
ssl
property that enables support for TLS/SSL connections.
This is useful for production databases, which can be supported by setting the rejectUnauthorized
attribute of ssl
object to false
.
During development, it’s recommended not to pass this option.
Example
Properties
connection
objectOptional
connection
objectOptionalredisUrl#
This configuration specifies the connection URL to Redis to store the Medusa server's session.
The Redis connection URL has the following format:
For a local Redis installation, the connection URL should be redis://localhost:6379
unless you’ve made any changes to the Redis configuration during installation.
Example
redisPrefix#
This configuration defines a prefix on all keys stored in Redis for the Medusa server's session. The default value is sess:
.
If this configuration option is provided, it is prepended to sess:
.
Example
redisOptions#
This configuration defines options to pass ioredis for the Redis connection used to store the Medusa server's session. Refer to ioredis’s RedisOptions documentation for the list of available options.
Example
sessionOptions#
This configuration defines additional options to pass to express-session, which is used to store the Medusa server's session.
Example
Properties
name
stringOptionalconnect.sid
.
Refer to express-session’s documentation for more details.resave
booleanOptionaltrue
.
Refer to express-session’s documentation for more details.rolling
booleanOptionalfalse
.
Refer to express-session’s documentation for more details.saveUninitialized
booleanOptionaltrue
.
Refer to express-session’s documentation for more details.secret
stringOptionalhttp.cookieSecret
is used.
Refer to express-session’s documentation for details.ttl
numberOptionalExpires
Set-Cookie
attribute of cookies. By default, its value is 10 * 60 * 60 * 1000
.
Refer to express-session’s documentation for details.workerMode#
Configure the application's worker mode.
Workers are processes running separately from the main application. They're useful for executing long-running or resource-heavy tasks in the background, such as importing products.
With a worker, these tasks are offloaded to a separate process. So, they won't affect the performance of the main application.
Medusa has three runtime modes:
- Use
shared
to run the application in a single process. - Use
worker
to run the a worker process only. - Use
server
to run the application server only.
In production, it's recommended to deploy two instances:
- One having the
workerMode
configuration set toserver
. - Another having the
workerMode
configuration set toworker
.
Example
http#
This property configures the application's http-specific settings.
Example
Properties
authCors
stringcors
is a string used to specify the accepted URLs or patterns for API Routes starting with /auth
. It can either be one accepted origin, or a comma-separated list of accepted origins.
Every origin in that list must either be:
- A URL. For example,
http://localhost:7001
. The URL must not end with a backslash; - Or a regular expression pattern that can match more than one origin. For example,
.example.com
. The regex pattern that Medusa tests for is^([/~@;%#'])(.*?)\1([gimsuy]*)$
.
storeCors
stringstore_cors
is a string used to specify the accepted URLs or patterns for store API Routes. It can either be one accepted origin, or a comma-separated list of accepted origins.
Every origin in that list must either be:
- A URL. For example,
http://localhost:8000
. The URL must not end with a backslash; - Or a regular expression pattern that can match more than one origin. For example,
.example.com
. The regex pattern that the backend tests for is^([/~@;%#'])(.*?)\1([gimsuy]*)$
.
adminCors
stringadmin_cors
is a string used to specify the accepted URLs or patterns for admin API Routes. It can either be one accepted origin, or a comma-separated list of accepted origins.
Every origin in that list must either be:
- A URL. For example,
http://localhost:7001
. The URL must not end with a backslash; - Or a regular expression pattern that can match more than one origin. For example,
.example.com
. The regex pattern that the backend tests for is^([/~@;%#'])(.*?)\1([gimsuy]*)$
.
jwtSecret
stringOptionalsupersecret
. However, in production, if this configuration is not set, an
error is thrown and the application crashes.jwtExpiresIn
stringOptional24h
.cookieSecret
stringOptionalsupersecret
. However, in production, if this configuration is not set, an error is thrown and
the application crashes.Configure HTTP compression from the application layer. If you have access to the HTTP server, the recommended approach would be to enable it there.
However, some platforms don't offer access to the HTTP layer and in those cases, this is a good alternative.
If you enable HTTP compression and you want to disable it for specific API Routes, you can pass in the request header "x-no-compression": true
.
Learn more in the API Reference.
"x-no-compression": true
.
Learn more in the API Reference.authMethodsPerActor
Record<string, string[]>Optionaluser
, customer
, or any custom actors).
For example, you only want to allow SSO logins for users
, while you want to allow email/password logins for customers
to the storefront.
authMethodsPerActor
is a a map where the actor type (eg. 'user') is the key, and the value is an array of supported auth provider IDs.restrictedFields
objectOptionalSpecifies the fields that can't be selected in the response unless specified in the allowed query config.
This is useful to restrict sensitive fields from being exposed in the API.
restrictedFields
objectOptionaladmin#
This property holds configurations for the Medusa Admin dashboard.
Example#
disable#
Whether to disable the admin dashboard. If set to true
, the admin dashboard is disabled,
in both development and production environments. The default value is false
.
Example
path#
The path to the admin dashboard. The default value is /app
.
The value cannot be one of the reserved paths:
/admin
/store
/auth
/
Example
outDir#
The directory where the admin build is outputted when you run the build
command.
The default value is ./build
.
Example
backendUrl#
The URL of your Medusa application. This is useful to set when you deploy the Medusa application.
Example
vite#
Configure the Vite configuration for the admin dashboard. This function receives the default Vite configuration
and returns the modified configuration. The default value is undefined
.
modules#
This property holds all custom modules installed in your Medusa application.
modules
is an array of objects, each holding a module's registration configurations. Each object has the following properties:
resolve
: a string indicating the path to the module relative tosrc
, or the module's NPM package name. For example,./modules/my-module
.options
: (optional) an object indicating the options to pass to the module.
Example#
featureFlags#
Some features in the Medusa application are guarded by a feature flag. This ensures constant shipping of new features while maintaining the engine’s stability.
You can enable a feature in your application by enabling its feature flag. Feature flags are enabled through either environment
variables or through this configuration property exported in medusa-config.ts
.
The featureFlags
's value is an object. Its properties are the names of the feature flags, and their value is a boolean indicating whether the feature flag is enabled.
You can find available feature flags and their key name here.