asyavee/medusa-store
1
0 Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

chore: update the medusa config TSDocs + options (#8697)

Browse Source
This commit is contained in:
Shahed Nasser authored and GitHub committed 2024-08-21 17:46:14 +03:00
1 parent a5707fd3bc
commit 539266559c
4 files changed
+230 -117
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

packages/core/types/src/common/config-module.ts
+101 -56
View File
@@ -16,6 +16,17 @@ export type AdminOptions = {
/** /**
* Whether to disable the admin dashboard. If set to `true`, the admin dashboard is disabled, * 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`. * in both development and production environments. The default value is `false`.
*
* @example
* ```js title="medusa-config.js"
* module.exports = defineConfig({
* admin: {
* disable: process.env.ADMIN_DISABLED === "true" ||
* false
* },
* // ...
* })
* ```
*/ */
disable?: boolean disable?: boolean
/** /**
@@ -26,15 +37,46 @@ export type AdminOptions = {
* - `/store` * - `/store`
* - `/auth` * - `/auth`
* - `/` * - `/`
*
* @example
* ```js title="medusa-config.js"
* module.exports = defineConfig({
* admin: {
* path: process.env.ADMIN_PATH || `/app`,
* },
* // ...
* })
* ```
*/ */
path?: `/${string}` path?: `/${string}`
/** /**
* The directory where the admin build is output. This is where the build process places the generated files. * The directory where the admin build is outputted when you run the `build` command.
* The default value is `./build`. * The default value is `./build`.
*
* @example
* ```js title="medusa-config.js"
* module.exports = defineConfig({
* admin: {
* outDir: process.env.ADMIN_BUILD_DIR || `./build`,
* },
* // ...
* })
* ```
*/ */
outDir?: string outDir?: string
/** /**
* The URL of your Medusa backend. Defaults to an empty string, which means requests will hit the same server that serves the dashboard. * The URL of your Medusa application. This is useful to set when you deploy the Medusa application.
*
* @example
* ```js title="medusa-config.js"
* module.exports = defineConfig({
* admin: {
* backendUrl: process.env.MEDUSA_BACKEND_URL ||
* "http://localhost:9000"
* },
* // ...
* })
* ```
*/ */
backendUrl?: string backendUrl?: string
/** /**
@@ -114,11 +156,11 @@ export type HttpCompressionOptions = {
/** /**
* @interface * @interface
* *
* Essential configurations related to the Medusa backend, such as database and CORS configurations. * Essential configurations related to the Medusa application, such as database and CORS configurations.
*/ */
export type ProjectConfigOptions = { export type ProjectConfigOptions = {
/** /**
* The name of the database to connect to. If specified in `databaseUrl`, then it’s not required to include it. * 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 * Make sure to create the PostgreSQL database before using it. You can check how to create a database in
* [PostgreSQL's documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html). * [PostgreSQL's documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html).
@@ -138,7 +180,7 @@ export type ProjectConfigOptions = {
databaseName?: string databaseName?: string
/** /**
* The connection URL of the database. The format of the connection URL for PostgreSQL is: * The PostgreSQL connection URL of the database, which is of the following format:
* *
* ```bash * ```bash
* postgres://[user][:password]@[host][:port]/[dbname] * postgres://[user][:password]@[host][:port]/[dbname]
@@ -192,19 +234,13 @@ export type ProjectConfigOptions = {
databaseSchema?: string databaseSchema?: string
/** /**
* This configuration specifies what database messages to log. Its value can be one of the following: * This configuration specifies whether database messages should be logged.
*
* - (default) A boolean value that indicates whether any messages should be logged.
* - The string value `all` that indicates all types of messages should be logged.
* - An array of log-level strings to indicate which type of messages to show in the logs. The strings can be `query`, `schema`, `error`, `warn`, `info`, `log`, or `migration`. Refer to [Typeorm’s documentation](https://typeorm.io/logging#logging-options) for more details on what each of these values means.
*
* If this configuration isn't set, its default value is `false`, meaning no database messages are logged.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
* module.exports = defineConfig({ * module.exports = defineConfig({
* projectConfig: { * projectConfig: {
* databaseLogging: ["query", "error"] * databaseLogging: false
* // ... * // ...
* }, * },
* // ... * // ...
@@ -223,8 +259,8 @@ export type ProjectConfigOptions = {
databaseType?: string databaseType?: string
/** /**
* An object that includes additional configurations to pass to the database connection for v2. You can pass any configuration. One defined configuration to pass is * This configuration is used to pass additional options to the database connection. You can pass any configuration. For example, pass the
* `ssl` which enables support for TLS/SSL connections. * `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`. * 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. * During development, it’s recommended not to pass this option.
@@ -262,7 +298,7 @@ export type ProjectConfigOptions = {
} }
/** /**
* Used to specify the URL to connect to Redis. This is only used for scheduled jobs. If you omit this configuration, scheduled jobs won't work. * This configuration specifies the connection URL to Redis to store the Medusa server's session.
* *
* :::note * :::note
* *
@@ -293,7 +329,7 @@ export type ProjectConfigOptions = {
redisUrl?: string redisUrl?: string
/** /**
* The prefix set on all keys stored in Redis. The default value is `sess:`. * 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:`. * If this configuration option is provided, it is prepended to `sess:`.
* *
@@ -311,7 +347,7 @@ export type ProjectConfigOptions = {
redisPrefix?: string redisPrefix?: string
/** /**
* An object of options to pass ioredis. You can refer to [ioredis’s RedisOptions documentation](https://redis.github.io/ioredis/index.html#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](https://redis.github.io/ioredis/index.html#RedisOptions)
* for the list of available options. * for the list of available options.
* *
* @example * @example
@@ -331,7 +367,7 @@ export type ProjectConfigOptions = {
redisOptions?: RedisOptions redisOptions?: RedisOptions
/** /**
* An object of options to pass to [express-session](https://www.npmjs.com/package/express-session). * This configuration defines additional options to pass to [express-session](https://www.npmjs.com/package/express-session), which is used to store the Medusa server's session.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -349,7 +385,7 @@ export type ProjectConfigOptions = {
sessionOptions?: SessionOptions sessionOptions?: SessionOptions
/** /**
* Configure HTTP compression from the application layer. If you have access to the HTTP server, the recommended approach would be to enable it there. * This property configures the 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. * 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`. * 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`.
@@ -374,6 +410,11 @@ export type ProjectConfigOptions = {
* // ... * // ...
* }) * })
* ``` * ```
*
* @ignore
*
* @privateRemarks
* Couldn't find any use for this option.
*/ */
jobsBatchSize?: number jobsBatchSize?: number
@@ -411,7 +452,7 @@ export type ProjectConfigOptions = {
workerMode?: "shared" | "worker" | "server" workerMode?: "shared" | "worker" | "server"
/** /**
* Configure the application's http-specific settings * This property configures the application's http-specific settings.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -433,8 +474,8 @@ export type ProjectConfigOptions = {
/** /**
* A random string used to create authentication tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security. * A random string used to create authentication tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security.
* *
* In a development environment, if this option is not set the default secret is `supersecret` However, in production, if this configuration is not set an error, an * In a development environment, if this option is not set the default secret is `supersecret`. However, in production, if this configuration is not set, an
* error is thrown and the backend crashes. * error is thrown and the application crashes.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -451,7 +492,9 @@ export type ProjectConfigOptions = {
*/ */
jwtSecret?: string jwtSecret?: string
/** /**
* The expiration time for the JWT token. If not provided, the default value is `24h`. * The expiration time for the JWT token. Its format is based off the [ms package](https://github.com/vercel/ms).
*
* If not provided, the default value is `24h`.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -470,8 +513,8 @@ export type ProjectConfigOptions = {
/** /**
* A random string used to create cookie tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security. * A random string used to create cookie tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security.
* *
* In a development environment, if this option is not set, the default secret is `supersecret` However, in production, if this configuration is not set, an error is thrown and * In a development environment, if this option is not set, the default secret is `supersecret`. However, in production, if this configuration is not set, an error is thrown and
* the backend crashes. * the application crashes.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -488,14 +531,14 @@ export type ProjectConfigOptions = {
*/ */
cookieSecret?: string cookieSecret?: string
/** /**
* The Medusa backend’s API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes. * The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.
* *
* `cors` 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. * `cors` 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: * Every origin in that list must either be:
* *
* 1. A URL. For example, `http://localhost:7001`. The URL must not end with a backslash; * 1. A URL. For example, `http://localhost:7001`. The URL must not end with a backslash;
* 2. 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]*)$`. * 2. 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]*)$`.
* *
* @example * @example
* Some example values of common use cases: * Some example values of common use cases:
@@ -545,9 +588,8 @@ export type ProjectConfigOptions = {
* Configure HTTP compression from the application layer. If you have access to the HTTP server, the recommended approach would be to enable it there. * 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. * However, some platforms don't offer access to the HTTP layer and in those cases, this is a good alternative.
* *
* Its value is an object that has the following properties:
*
* 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`. * 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](https://docs.medusajs.com/v2/api/store#http-compression).
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -569,7 +611,7 @@ export type ProjectConfigOptions = {
*/ */
compression?: HttpCompressionOptions compression?: HttpCompressionOptions
/** /**
* The Medusa backend’s API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes. * The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.
* *
* `store_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. * `store_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.
* *
@@ -623,7 +665,7 @@ export type ProjectConfigOptions = {
storeCors: string storeCors: string
/** /**
* The Medusa backend’s API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes. * The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.
* *
* `admin_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. * `admin_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.
* *
@@ -677,11 +719,10 @@ export type ProjectConfigOptions = {
adminCors: string adminCors: string
/** /**
* Optionally you can specify the supported authentication providers per actor type (such as user, customer, or any custom actors). * This configuration specifies the supported authentication providers per actor type (such as `user`, `customer`, or any custom actors).
* For example, you only want to allow SSO logins for `users` to the admin, while you want to allow email/password logins for `customers` to the storefront. * 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 an array of supported auth providers as the value.
* *
* `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.
* *
* @example * @example
* Some example values of common use cases: * Some example values of common use cases:
@@ -694,7 +735,7 @@ export type ProjectConfigOptions = {
* http: { * http: {
* authMethodsPerActor: { * authMethodsPerActor: {
* user: ["email"], * user: ["email"],
* customer: ["emailpas", "google"] * customer: ["emailpass", "google"]
* } * }
* } * }
* // ... * // ...
@@ -710,14 +751,15 @@ export type ProjectConfigOptions = {
/** /**
* @interface * @interface
* *
* The configurations for your Medusa backend are in `medusa-config.js` located in the root of your Medusa project. The configurations include database, modules, and plugin configurations, among other configurations. * The configurations for your Medusa application are in `medusa-config.js` located in the root of your Medusa project. The configurations include configurations for database, modules, and more.
* *
* `medusa-config.js` exports an object having the following properties: * `medusa-config.js` exports the value returned by the `defineConfig` utility function imported from `@medusajs/utils`.
*
* `defineConfig` accepts as a parameter an object with the following properties:
* *
* - {@link ConfigModule.projectConfig | projectConfig} (required): An object that holds general configurations related to the Medusa backend, such as database or CORS configurations. * - {@link ConfigModule.projectConfig | projectConfig} (required): An object that holds general configurations related to the Medusa application, such as database or CORS configurations.
* - {@link ConfigModule.admin | admin}: An object that holds admin-related configurations. * - {@link ConfigModule.admin | admin}: An object that holds admin-related configurations.
* - {@link ConfigModule.plugins | plugins}: An array of plugin configurations that defines what plugins are installed and optionally specifies each of their configurations. * - {@link ConfigModule.modules | modules}: An object that configures the Medusa application's modules.
* - {@link ConfigModule.modules | modules}: An object that defines what modules are installed and optionally specifies each of their configurations.
* - {@link ConfigModule.featureFlags | featureFlags}: An object that enables or disables features guarded by a feature flag. * - {@link ConfigModule.featureFlags | featureFlags}: An object that enables or disables features guarded by a feature flag.
* *
* For example: * For example:
@@ -745,19 +787,19 @@ export type ProjectConfigOptions = {
* *
* It's highly recommended to store the values of configurations in environment variables, then reference them within `medusa-config.js`. * It's highly recommended to store the values of configurations in environment variables, then reference them within `medusa-config.js`.
* *
* During development, you can set your environment variables in the `.env` file at the root of your Medusa backend project. In production, * 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. * setting the environment variables depends on the hosting provider.
* *
* --- * ---
*/ */
export type ConfigModule = { export type ConfigModule = {
/** /**
* This property holds essential configurations related to the Medusa backend, such as database and CORS configurations. * This property holds essential configurations related to the Medusa application, such as database and CORS configurations.
*/ */
projectConfig: ProjectConfigOptions projectConfig: ProjectConfigOptions
/** /**
* Admin dashboard configurations. * This property holds configurations for the Medusa Admin dashboard.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -817,18 +859,21 @@ export type ConfigModule = {
)[] )[]
/** /**
* In Medusa, commerce and core logic are modularized to allow developers to extend or replace certain [modules](https://docs.medusajs.com/development/modules/overview) * This property holds all custom modules installed in your Medusa application.
* with custom implementations. *
* * :::note
* Aside from installing the module with NPM, you must add it to the exported object in `medusa-config.js`. *
* Medusa's commerce modules are configured by default, so only
* add them to this property if you're changing their configurations or adding providers to a module.
*
* :::
* *
* The keys of the `modules` configuration object refer to the module's registration name. Its value can be one of the following: * The keys of the `modules` configuration object refer to the module's registration name. Its value can be one of the following:
* *
* 1. A boolean value indicating whether the module type is enabled. This is only supported for Medusa's commerce and architectural modules; * 1. A boolean value indicating whether the module type is enabled. This is only supported for Medusa's commerce and architectural modules;
* 2. Or an object having the following properties: * 2. Or an object having the following properties:
* 1. `resolve`: a string indicating the path to the module relative to `src`, or the module's NPM package name. * 1. `resolve`: a string indicating the path to the module relative to `src`, or the module's NPM package name. For example, `./modules/my-module`.
* 2. `options`: (optional) an object indicating the options to pass to the module. * 2. `options`: (optional) an object indicating the options to pass to the module.
* 3. `definition`: (optional) an object of extra configurations, such as `isQueryable` used when a module has relationships.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -848,12 +893,12 @@ export type ConfigModule = {
> >
/** /**
* Some features in the Medusa backend are guarded by a feature flag. This ensures constant shipping of new features while maintaining the engine’s stability. * 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 specify whether a feature should or shouldn’t be used in your backend by enabling its feature flag. Feature flags can be enabled through either environment * 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 exported in `medusa-config.js`. * variables or through this configuration property exported in `medusa-config.js`.
* *
* The `featureFlags` configuration is an object. Its properties are the names of the feature flags. Each property’s value is a boolean indicating whether the feature flag is enabled. * 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](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/loaders/feature-flags). * You can find available feature flags and their key name [here](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/loaders/feature-flags).
* *
@@ -861,7 +906,7 @@ export type ConfigModule = {
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
* module.exports = defineConfig({ * module.exports = defineConfig({
* featureFlags: { * featureFlags: {
* product_categories: true, * analytics: true,
* // ... * // ...
* } * }
* // ... * // ...
packages/framework/framework/src/config/types.ts
+121 -59
View File
@@ -15,6 +15,17 @@ export type AdminOptions = {
/** /**
* Whether to disable the admin dashboard. If set to `true`, the admin dashboard is disabled, * 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`. * in both development and production environments. The default value is `false`.
*
* @example
* ```js title="medusa-config.js"
* module.exports = defineConfig({
* admin: {
* disable: process.env.ADMIN_DISABLED === "true" ||
* false
* },
* // ...
* })
* ```
*/ */
disable?: boolean disable?: boolean
/** /**
@@ -25,15 +36,46 @@ export type AdminOptions = {
* - `/store` * - `/store`
* - `/auth` * - `/auth`
* - `/` * - `/`
*
* @example
* ```js title="medusa-config.js"
* module.exports = defineConfig({
* admin: {
* path: process.env.ADMIN_PATH || `/app`,
* },
* // ...
* })
* ```
*/ */
path?: `/${string}` path?: `/${string}`
/** /**
* The directory where the admin build is output. This is where the build process places the generated files. * The directory where the admin build is outputted when you run the `build` command.
* The default value is `./build`. * The default value is `./build`.
*
* @example
* ```js title="medusa-config.js"
* module.exports = defineConfig({
* admin: {
* outDir: process.env.ADMIN_BUILD_DIR || `./build`,
* },
* // ...
* })
* ```
*/ */
outDir?: string outDir?: string
/** /**
* The URL of your Medusa backend. Defaults to an empty string, which means requests will hit the same server that serves the dashboard. * The URL of your Medusa application. This is useful to set when you deploy the Medusa application.
*
* @example
* ```js title="medusa-config.js"
* module.exports = defineConfig({
* admin: {
* backendUrl: process.env.MEDUSA_BACKEND_URL ||
* "http://localhost:9000"
* },
* // ...
* })
* ```
*/ */
backendUrl?: string backendUrl?: string
/** /**
@@ -113,11 +155,11 @@ export type HttpCompressionOptions = {
/** /**
* @interface * @interface
* *
* Essential configurations related to the Medusa backend, such as database and CORS configurations. * Essential configurations related to the Medusa application, such as database and CORS configurations.
*/ */
export type ProjectConfigOptions = { export type ProjectConfigOptions = {
/** /**
* The name of the database to connect to. If specified in `databaseUrl`, then it’s not required to include it. * 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 * Make sure to create the PostgreSQL database before using it. You can check how to create a database in
* [PostgreSQL's documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html). * [PostgreSQL's documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html).
@@ -137,7 +179,7 @@ export type ProjectConfigOptions = {
databaseName?: string databaseName?: string
/** /**
* The connection URL of the database. The format of the connection URL for PostgreSQL is: * The PostgreSQL connection URL of the database, which is of the following format:
* *
* ```bash * ```bash
* postgres://[user][:password]@[host][:port]/[dbname] * postgres://[user][:password]@[host][:port]/[dbname]
@@ -191,19 +233,13 @@ export type ProjectConfigOptions = {
databaseSchema?: string databaseSchema?: string
/** /**
* This configuration specifies what database messages to log. Its value can be one of the following: * This configuration specifies whether database messages should be logged.
*
* - (default) A boolean value that indicates whether any messages should be logged.
* - The string value `all` that indicates all types of messages should be logged.
* - An array of log-level strings to indicate which type of messages to show in the logs. The strings can be `query`, `schema`, `error`, `warn`, `info`, `log`, or `migration`. Refer to [Typeorm’s documentation](https://typeorm.io/logging#logging-options) for more details on what each of these values means.
*
* If this configuration isn't set, its default value is `false`, meaning no database messages are logged.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
* module.exports = defineConfig({ * module.exports = defineConfig({
* projectConfig: { * projectConfig: {
* databaseLogging: boolean * databaseLogging: false
* // ... * // ...
* }, * },
* // ... * // ...
@@ -222,11 +258,17 @@ export type ProjectConfigOptions = {
databaseType?: string databaseType?: string
/** /**
* An object that includes additional configurations to pass to the database connection for v2. You can pass any configuration. One defined configuration to pass is * This configuration is used to pass additional options to the database connection. You can pass any configuration. For example, pass the
* `ssl` which enables support for TLS/SSL connections. * `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`. * 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. * During development, it’s recommended not to pass this option.
*
* :::note
*
* Make sure to add to the end of the database URL `?ssl_mode=disable` as well when disabling `rejectUnauthorized`.
*
* :::
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -255,7 +297,7 @@ export type ProjectConfigOptions = {
} }
/** /**
* Used to specify the URL to connect to Redis. This is only used for scheduled jobs. If you omit this configuration, scheduled jobs won't work. * This configuration specifies the connection URL to Redis to store the Medusa server's session.
* *
* :::note * :::note
* *
@@ -286,7 +328,7 @@ export type ProjectConfigOptions = {
redisUrl?: string redisUrl?: string
/** /**
* The prefix set on all keys stored in Redis. The default value is `sess:`. * 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:`. * If this configuration option is provided, it is prepended to `sess:`.
* *
@@ -304,7 +346,7 @@ export type ProjectConfigOptions = {
redisPrefix?: string redisPrefix?: string
/** /**
* An object of options to pass ioredis. You can refer to [ioredis’s RedisOptions documentation](https://redis.github.io/ioredis/index.html#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](https://redis.github.io/ioredis/index.html#RedisOptions)
* for the list of available options. * for the list of available options.
* *
* @example * @example
@@ -324,7 +366,7 @@ export type ProjectConfigOptions = {
redisOptions?: RedisOptions redisOptions?: RedisOptions
/** /**
* An object of options to pass to [express-session](https://www.npmjs.com/package/express-session). * This configuration defines additional options to pass to [express-session](https://www.npmjs.com/package/express-session), which is used to store the Medusa server's session.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -342,7 +384,7 @@ export type ProjectConfigOptions = {
sessionOptions?: SessionOptions sessionOptions?: SessionOptions
/** /**
* Configure HTTP compression from the application layer. If you have access to the HTTP server, the recommended approach would be to enable it there. * This property configures the 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. * 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`. * 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`.
@@ -367,23 +409,39 @@ export type ProjectConfigOptions = {
* // ... * // ...
* }) * })
* ``` * ```
*
* @ignore
*
* @privateRemarks
* Couldn't find any use for this option.
*/ */
jobsBatchSize?: number jobsBatchSize?: number
/** /**
* Configure the application's worker mode. Default is `shared`. * 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.
*
* ![Diagram showcasing how the server and worker work together](https://res.cloudinary.com/dza7lstvk/image/upload/fl_lossy/f_auto/r_16/ar_16:9,c_pad/v1/Medusa%20Book/medusa-worker_klkbch.jpg?_a=BATFJtAA0)
*
* Medusa has three runtime modes:
* *
* - Use `shared` to run the application in a single process. * - Use `shared` to run the application in a single process.
* - Use `worker` to run the a worker process only. * - Use `worker` to run the a worker process only.
* - Use `server` to run the application server only. * - Use `server` to run the application server only.
* *
* Learn more in [this guide](https://docs.medusajs.com/development/medusa-worker). * In production, it's recommended to deploy two instances:
*
* 1. One having the `workerMode` configuration set to `server`.
* 2. Another having the `workerMode` configuration set to `worker`.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
* module.exports = defineConfig({ * module.exports = defineConfig({
* projectConfig: { * projectConfig: {
* workerMode: "shared" * workerMode: process.env.WORKER_MODE || "shared"
* // ... * // ...
* }, * },
* // ... * // ...
@@ -393,7 +451,7 @@ export type ProjectConfigOptions = {
workerMode?: "shared" | "worker" | "server" workerMode?: "shared" | "worker" | "server"
/** /**
* Configure the application's http-specific settings * This property configures the application's http-specific settings.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -415,8 +473,8 @@ export type ProjectConfigOptions = {
/** /**
* A random string used to create authentication tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security. * A random string used to create authentication tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security.
* *
* In a development environment, if this option is not set the default secret is `supersecret` However, in production, if this configuration is not set an error, an * In a development environment, if this option is not set the default secret is `supersecret`. However, in production, if this configuration is not set, an
* error is thrown and the backend crashes. * error is thrown and the application crashes.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -433,7 +491,9 @@ export type ProjectConfigOptions = {
*/ */
jwtSecret?: string jwtSecret?: string
/** /**
* The expiration time for the JWT token. If not provided, the default value is `24h`. * The expiration time for the JWT token. Its format is based off the [ms package](https://github.com/vercel/ms).
*
* If not provided, the default value is `24h`.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -452,8 +512,8 @@ export type ProjectConfigOptions = {
/** /**
* A random string used to create cookie tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security. * A random string used to create cookie tokens in the http layer. Although this configuration option is not required, it’s highly recommended to set it for better security.
* *
* In a development environment, if this option is not set, the default secret is `supersecret` However, in production, if this configuration is not set, an error is thrown and * In a development environment, if this option is not set, the default secret is `supersecret`. However, in production, if this configuration is not set, an error is thrown and
* the backend crashes. * the application crashes.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -470,14 +530,14 @@ export type ProjectConfigOptions = {
*/ */
cookieSecret?: string cookieSecret?: string
/** /**
* The Medusa backend’s API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes. * The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.
* *
* `cors` 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. * `cors` 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: * Every origin in that list must either be:
* *
* 1. A URL. For example, `http://localhost:7001`. The URL must not end with a backslash; * 1. A URL. For example, `http://localhost:7001`. The URL must not end with a backslash;
* 2. 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]*)$`. * 2. 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]*)$`.
* *
* @example * @example
* Some example values of common use cases: * Some example values of common use cases:
@@ -527,9 +587,8 @@ export type ProjectConfigOptions = {
* Configure HTTP compression from the application layer. If you have access to the HTTP server, the recommended approach would be to enable it there. * 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. * However, some platforms don't offer access to the HTTP layer and in those cases, this is a good alternative.
* *
* Its value is an object that has the following properties:
*
* 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`. * 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](https://docs.medusajs.com/v2/api/store#http-compression).
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -551,7 +610,7 @@ export type ProjectConfigOptions = {
*/ */
compression?: HttpCompressionOptions compression?: HttpCompressionOptions
/** /**
* The Medusa backend’s API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes. * The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.
* *
* `store_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. * `store_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.
* *
@@ -605,7 +664,7 @@ export type ProjectConfigOptions = {
storeCors: string storeCors: string
/** /**
* The Medusa backend’s API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes. * The Medusa application's API Routes are protected by Cross-Origin Resource Sharing (CORS). So, only allowed URLs or URLs matching a specified pattern can send requests to the backend’s API Routes.
* *
* `admin_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. * `admin_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.
* *
@@ -659,11 +718,10 @@ export type ProjectConfigOptions = {
adminCors: string adminCors: string
/** /**
* Optionally you can specify the supported authentication providers per actor type (such as user, customer, or any custom actors). * This configuration specifies the supported authentication providers per actor type (such as `user`, `customer`, or any custom actors).
* For example, you only want to allow SSO logins for `users` to the admin, while you want to allow email/password logins for `customers` to the storefront. * 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 an array of supported auth providers as the value.
* *
* `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.
* *
* @example * @example
* Some example values of common use cases: * Some example values of common use cases:
@@ -676,7 +734,7 @@ export type ProjectConfigOptions = {
* http: { * http: {
* authMethodsPerActor: { * authMethodsPerActor: {
* user: ["email"], * user: ["email"],
* customer: ["emailpas", "google"] * customer: ["emailpass", "google"]
* } * }
* } * }
* // ... * // ...
@@ -692,14 +750,15 @@ export type ProjectConfigOptions = {
/** /**
* @interface * @interface
* *
* The configurations for your Medusa backend are in `medusa-config.js` located in the root of your Medusa project. The configurations include database, modules, and plugin configurations, among other configurations. * The configurations for your Medusa application are in `medusa-config.js` located in the root of your Medusa project. The configurations include configurations for database, modules, and more.
* *
* `medusa-config.js` exports an object having the following properties: * `medusa-config.js` exports the value returned by the `defineConfig` utility function imported from `@medusajs/utils`.
*
* `defineConfig` accepts as a parameter an object with the following properties:
* *
* - {@link ConfigModule.projectConfig | projectConfig} (required): An object that holds general configurations related to the Medusa backend, such as database or CORS configurations. * - {@link ConfigModule.projectConfig | projectConfig} (required): An object that holds general configurations related to the Medusa application, such as database or CORS configurations.
* - {@link ConfigModule.admin | admin}: An object that holds admin-related configurations. * - {@link ConfigModule.admin | admin}: An object that holds admin-related configurations.
* - {@link ConfigModule.plugins | plugins}: An array of plugin configurations that defines what plugins are installed and optionally specifies each of their configurations. * - {@link ConfigModule.modules | modules}: An object that configures the Medusa application's modules.
* - {@link ConfigModule.modules | modules}: An object that defines what modules are installed and optionally specifies each of their configurations.
* - {@link ConfigModule.featureFlags | featureFlags}: An object that enables or disables features guarded by a feature flag. * - {@link ConfigModule.featureFlags | featureFlags}: An object that enables or disables features guarded by a feature flag.
* *
* For example: * For example:
@@ -727,19 +786,19 @@ export type ProjectConfigOptions = {
* *
* It's highly recommended to store the values of configurations in environment variables, then reference them within `medusa-config.js`. * It's highly recommended to store the values of configurations in environment variables, then reference them within `medusa-config.js`.
* *
* During development, you can set your environment variables in the `.env` file at the root of your Medusa backend project. In production, * 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. * setting the environment variables depends on the hosting provider.
* *
* --- * ---
*/ */
export type ConfigModule = { export type ConfigModule = {
/** /**
* This property holds essential configurations related to the Medusa backend, such as database and CORS configurations. * This property holds essential configurations related to the Medusa application, such as database and CORS configurations.
*/ */
projectConfig: ProjectConfigOptions projectConfig: ProjectConfigOptions
/** /**
* Admin dashboard configurations. * This property holds configurations for the Medusa Admin dashboard.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -799,18 +858,21 @@ export type ConfigModule = {
)[] )[]
/** /**
* In Medusa, commerce and core logic are modularized to allow developers to extend or replace certain [modules](https://docs.medusajs.com/development/modules/overview) * This property holds all custom modules installed in your Medusa application.
* with custom implementations. *
* * :::note
* Aside from installing the module with NPM, you must add it to the exported object in `medusa-config.js`. *
* Medusa's commerce modules are configured by default, so only
* add them to this property if you're changing their configurations or adding providers to a module.
*
* :::
* *
* The keys of the `modules` configuration object refer to the module's registration name. Its value can be one of the following: * The keys of the `modules` configuration object refer to the module's registration name. Its value can be one of the following:
* *
* 1. A boolean value indicating whether the module type is enabled. This is only supported for Medusa's commerce and architectural modules; * 1. A boolean value indicating whether the module type is enabled. This is only supported for Medusa's commerce and architectural modules;
* 2. Or an object having the following properties: * 2. Or an object having the following properties:
* 1. `resolve`: a string indicating the path to the module relative to `src`, or the module's NPM package name. * 1. `resolve`: a string indicating the path to the module relative to `src`, or the module's NPM package name. For example, `./modules/my-module`.
* 2. `options`: (optional) an object indicating the options to pass to the module. * 2. `options`: (optional) an object indicating the options to pass to the module.
* 3. `definition`: (optional) an object of extra configurations, such as `isQueryable` used when a module has relationships.
* *
* @example * @example
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
@@ -830,12 +892,12 @@ export type ConfigModule = {
> >
/** /**
* Some features in the Medusa backend are guarded by a feature flag. This ensures constant shipping of new features while maintaining the engine’s stability. * 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 specify whether a feature should or shouldn’t be used in your backend by enabling its feature flag. Feature flags can be enabled through either environment * 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 exported in `medusa-config.js`. * variables or through this configuration property exported in `medusa-config.js`.
* *
* The `featureFlags` configuration is an object. Its properties are the names of the feature flags. Each property’s value is a boolean indicating whether the feature flag is enabled. * 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](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/loaders/feature-flags). * You can find available feature flags and their key name [here](https://github.com/medusajs/medusa/tree/develop/packages/medusa/src/loaders/feature-flags).
* *
@@ -843,7 +905,7 @@ export type ConfigModule = {
* ```js title="medusa-config.js" * ```js title="medusa-config.js"
* module.exports = defineConfig({ * module.exports = defineConfig({
* featureFlags: { * featureFlags: {
* product_categories: true, * analytics: true,
* // ... * // ...
* } * }
* // ... * // ...
www/utils/packages/typedoc-config/framework.json
+6
View File
@@ -0,0 +1,6 @@
{
"$schema": "http://json.schemastore.org/tsconfig",
"extends": [
"../../../../packages/framework/framework/tsconfig.json"
]
}
www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts
+2 -2
View File
@@ -61,8 +61,8 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
], ],
}), }),
"medusa-config": getOptions({ "medusa-config": getOptions({
entryPointPath: "packages/core/types/src/common/config-module.ts", entryPointPath: "packages/framework/framework/src/config/types.ts",
tsConfigName: "types.json", tsConfigName: "framework.json",
name: "medusa-config", name: "medusa-config",
}), }),
medusa: getOptions({ medusa: getOptions({