From 539266559c1af506824bd4ac1c3032af53723fee Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 21 Aug 2024 17:46:14 +0300 Subject: [PATCH] chore: update the medusa config TSDocs + options (#8697) --- .../core/types/src/common/config-module.ts | 157 +++++++++------ .../framework/framework/src/config/types.ts | 180 ++++++++++++------ .../packages/typedoc-config/framework.json | 6 + .../src/constants/custom-options.ts | 4 +- 4 files changed, 230 insertions(+), 117 deletions(-) create mode 100644 www/utils/packages/typedoc-config/framework.json diff --git a/packages/core/types/src/common/config-module.ts b/packages/core/types/src/common/config-module.ts index 28f1e4b799..def7521fb7 100644 --- a/packages/core/types/src/common/config-module.ts +++ b/packages/core/types/src/common/config-module.ts @@ -16,6 +16,17 @@ export type AdminOptions = { /** * 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 + * ```js title="medusa-config.js" + * module.exports = defineConfig({ + * admin: { + * disable: process.env.ADMIN_DISABLED === "true" || + * false + * }, + * // ... + * }) + * ``` */ disable?: boolean /** @@ -26,15 +37,46 @@ export type AdminOptions = { * - `/store` * - `/auth` * - `/` + * + * @example + * ```js title="medusa-config.js" + * module.exports = defineConfig({ + * admin: { + * path: process.env.ADMIN_PATH || `/app`, + * }, + * // ... + * }) + * ``` */ 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`. + * + * @example + * ```js title="medusa-config.js" + * module.exports = defineConfig({ + * admin: { + * outDir: process.env.ADMIN_BUILD_DIR || `./build`, + * }, + * // ... + * }) + * ``` */ 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 /** @@ -114,11 +156,11 @@ export type HttpCompressionOptions = { /** * @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 = { /** - * 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 * [PostgreSQL's documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html). @@ -138,7 +180,7 @@ export type ProjectConfigOptions = { 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 * postgres://[user][:password]@[host][:port]/[dbname] @@ -192,19 +234,13 @@ export type ProjectConfigOptions = { databaseSchema?: string /** - * This configuration specifies what database messages to log. Its value can be one of the following: - * - * - (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. + * This configuration specifies whether database messages should be logged. * * @example * ```js title="medusa-config.js" * module.exports = defineConfig({ * projectConfig: { - * databaseLogging: ["query", "error"] + * databaseLogging: false * // ... * }, * // ... @@ -223,8 +259,8 @@ export type ProjectConfigOptions = { 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 - * `ssl` which enables support for TLS/SSL connections. + * 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. @@ -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 * @@ -293,7 +329,7 @@ export type ProjectConfigOptions = { 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:`. * @@ -311,7 +347,7 @@ export type ProjectConfigOptions = { 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. * * @example @@ -331,7 +367,7 @@ export type ProjectConfigOptions = { 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 * ```js title="medusa-config.js" @@ -349,7 +385,7 @@ export type ProjectConfigOptions = { 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. * * 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 @@ -411,7 +452,7 @@ export type ProjectConfigOptions = { workerMode?: "shared" | "worker" | "server" /** - * Configure the application's http-specific settings + * This property configures the application's http-specific settings. * * @example * ```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. * - * 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 - * error is thrown and the backend crashes. + * 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 application crashes. * * @example * ```js title="medusa-config.js" @@ -451,7 +492,9 @@ export type ProjectConfigOptions = { */ 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 * ```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. * - * 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. + * 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 application crashes. * * @example * ```js title="medusa-config.js" @@ -488,14 +531,14 @@ export type ProjectConfigOptions = { */ 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. * * Every origin in that list must either be: * * 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 * 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. * 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`. + * Learn more in the [API Reference](https://docs.medusajs.com/v2/api/store#http-compression). * * @example * ```js title="medusa-config.js" @@ -569,7 +611,7 @@ export type ProjectConfigOptions = { */ 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. * @@ -623,7 +665,7 @@ export type ProjectConfigOptions = { 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. * @@ -677,11 +719,10 @@ export type ProjectConfigOptions = { adminCors: string /** - * Optionally you can specify 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. - * - * `authMethodsPerActor` is a a map where the actor type (eg. 'user') is the key, and an array of supported auth providers as the value. + * 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`, 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. * * @example * Some example values of common use cases: @@ -694,7 +735,7 @@ export type ProjectConfigOptions = { * http: { * authMethodsPerActor: { * user: ["email"], - * customer: ["emailpas", "google"] + * customer: ["emailpass", "google"] * } * } * // ... @@ -710,14 +751,15 @@ export type ProjectConfigOptions = { /** * @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.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 defines what modules are installed and optionally specifies each of their configurations. + * - {@link ConfigModule.modules | modules}: An object that configures the Medusa application's modules. * - {@link ConfigModule.featureFlags | featureFlags}: An object that enables or disables features guarded by a feature flag. * * 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`. * - * 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. * * --- */ 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 /** - * Admin dashboard configurations. + * This property holds configurations for the Medusa Admin dashboard. * * @example * ```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) - * with custom implementations. - * - * Aside from installing the module with NPM, you must add it to the exported object in `medusa-config.js`. + * This property holds all custom modules installed in your Medusa application. + * + * :::note + * + * 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: * * 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: - * 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. - * 3. `definition`: (optional) an object of extra configurations, such as `isQueryable` used when a module has relationships. * * @example * ```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 - * variables or through this configuration exported in `medusa-config.js`. + * 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.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). * @@ -861,7 +906,7 @@ export type ConfigModule = { * ```js title="medusa-config.js" * module.exports = defineConfig({ * featureFlags: { - * product_categories: true, + * analytics: true, * // ... * } * // ... diff --git a/packages/framework/framework/src/config/types.ts b/packages/framework/framework/src/config/types.ts index 8240c56158..5d5ab60e14 100644 --- a/packages/framework/framework/src/config/types.ts +++ b/packages/framework/framework/src/config/types.ts @@ -15,6 +15,17 @@ export type AdminOptions = { /** * 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 + * ```js title="medusa-config.js" + * module.exports = defineConfig({ + * admin: { + * disable: process.env.ADMIN_DISABLED === "true" || + * false + * }, + * // ... + * }) + * ``` */ disable?: boolean /** @@ -25,15 +36,46 @@ export type AdminOptions = { * - `/store` * - `/auth` * - `/` + * + * @example + * ```js title="medusa-config.js" + * module.exports = defineConfig({ + * admin: { + * path: process.env.ADMIN_PATH || `/app`, + * }, + * // ... + * }) + * ``` */ 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`. + * + * @example + * ```js title="medusa-config.js" + * module.exports = defineConfig({ + * admin: { + * outDir: process.env.ADMIN_BUILD_DIR || `./build`, + * }, + * // ... + * }) + * ``` */ 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 /** @@ -113,11 +155,11 @@ export type HttpCompressionOptions = { /** * @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 = { /** - * 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 * [PostgreSQL's documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html). @@ -137,7 +179,7 @@ export type ProjectConfigOptions = { 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 * postgres://[user][:password]@[host][:port]/[dbname] @@ -191,19 +233,13 @@ export type ProjectConfigOptions = { databaseSchema?: string /** - * This configuration specifies what database messages to log. Its value can be one of the following: - * - * - (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. + * This configuration specifies whether database messages should be logged. * * @example * ```js title="medusa-config.js" * module.exports = defineConfig({ * projectConfig: { - * databaseLogging: boolean + * databaseLogging: false * // ... * }, * // ... @@ -222,11 +258,17 @@ export type ProjectConfigOptions = { 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 - * `ssl` which enables support for TLS/SSL connections. + * 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. + * + * :::note + * + * Make sure to add to the end of the database URL `?ssl_mode=disable` as well when disabling `rejectUnauthorized`. + * + * ::: * * @example * ```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 * @@ -286,7 +328,7 @@ export type ProjectConfigOptions = { 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:`. * @@ -304,7 +346,7 @@ export type ProjectConfigOptions = { 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. * * @example @@ -324,7 +366,7 @@ export type ProjectConfigOptions = { 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 * ```js title="medusa-config.js" @@ -342,7 +384,7 @@ export type ProjectConfigOptions = { 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. * * 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 /** - * 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 `worker` to run the a worker process 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 * ```js title="medusa-config.js" * module.exports = defineConfig({ * projectConfig: { - * workerMode: "shared" + * workerMode: process.env.WORKER_MODE || "shared" * // ... * }, * // ... @@ -393,7 +451,7 @@ export type ProjectConfigOptions = { workerMode?: "shared" | "worker" | "server" /** - * Configure the application's http-specific settings + * This property configures the application's http-specific settings. * * @example * ```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. * - * 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 - * error is thrown and the backend crashes. + * 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 application crashes. * * @example * ```js title="medusa-config.js" @@ -433,7 +491,9 @@ export type ProjectConfigOptions = { */ 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 * ```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. * - * 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. + * 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 application crashes. * * @example * ```js title="medusa-config.js" @@ -470,14 +530,14 @@ export type ProjectConfigOptions = { */ 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. * * Every origin in that list must either be: * * 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 * 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. * 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`. + * Learn more in the [API Reference](https://docs.medusajs.com/v2/api/store#http-compression). * * @example * ```js title="medusa-config.js" @@ -551,7 +610,7 @@ export type ProjectConfigOptions = { */ 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. * @@ -605,7 +664,7 @@ export type ProjectConfigOptions = { 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. * @@ -659,11 +718,10 @@ export type ProjectConfigOptions = { adminCors: string /** - * Optionally you can specify 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. - * - * `authMethodsPerActor` is a a map where the actor type (eg. 'user') is the key, and an array of supported auth providers as the value. + * 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`, 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. * * @example * Some example values of common use cases: @@ -676,7 +734,7 @@ export type ProjectConfigOptions = { * http: { * authMethodsPerActor: { * user: ["email"], - * customer: ["emailpas", "google"] + * customer: ["emailpass", "google"] * } * } * // ... @@ -692,14 +750,15 @@ export type ProjectConfigOptions = { /** * @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.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 defines what modules are installed and optionally specifies each of their configurations. + * - {@link ConfigModule.modules | modules}: An object that configures the Medusa application's modules. * - {@link ConfigModule.featureFlags | featureFlags}: An object that enables or disables features guarded by a feature flag. * * 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`. * - * 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. * * --- */ 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 /** - * Admin dashboard configurations. + * This property holds configurations for the Medusa Admin dashboard. * * @example * ```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) - * with custom implementations. - * - * Aside from installing the module with NPM, you must add it to the exported object in `medusa-config.js`. + * This property holds all custom modules installed in your Medusa application. + * + * :::note + * + * 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: * * 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: - * 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. - * 3. `definition`: (optional) an object of extra configurations, such as `isQueryable` used when a module has relationships. * * @example * ```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 - * variables or through this configuration exported in `medusa-config.js`. + * 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.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). * @@ -843,7 +905,7 @@ export type ConfigModule = { * ```js title="medusa-config.js" * module.exports = defineConfig({ * featureFlags: { - * product_categories: true, + * analytics: true, * // ... * } * // ... diff --git a/www/utils/packages/typedoc-config/framework.json b/www/utils/packages/typedoc-config/framework.json new file mode 100644 index 0000000000..d3f132ea01 --- /dev/null +++ b/www/utils/packages/typedoc-config/framework.json @@ -0,0 +1,6 @@ +{ + "$schema": "http://json.schemastore.org/tsconfig", + "extends": [ + "../../../../packages/framework/framework/tsconfig.json" + ] +} \ No newline at end of file diff --git a/www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts b/www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts index 8f55f6cbeb..e76d7f0093 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts @@ -61,8 +61,8 @@ const customOptions: Record> = { ], }), "medusa-config": getOptions({ - entryPointPath: "packages/core/types/src/common/config-module.ts", - tsConfigName: "types.json", + entryPointPath: "packages/framework/framework/src/config/types.ts", + tsConfigName: "framework.json", name: "medusa-config", }), medusa: getOptions({