diff --git a/www/apps/docs/content/admin/configuration.md b/www/apps/docs/content/admin/configuration.md deleted file mode 100644 index ace083e2ed..0000000000 --- a/www/apps/docs/content/admin/configuration.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -description: "In this document, you'll learn about the different ways you can configure the admin dashboard for your custom use cases." ---- - -# Admin Custom Configuration - -In this document, you'll learn about the different ways you can configure the admin dashboard for your custom use cases. - -## Admin CLI - -### Build Command Options - -The `build` command in the admin CLI allows you to manually build the admin dashboard. If you intend to use it, you should typically add it to the `package.json` of the Medusa backend: - -```json title="package.json" -{ - "scripts": { - // other scripts... - "build:admin": "medusa-admin build" - } -} -``` - -You can add the following option to the `medusa-admin build` command: - -- `--deployment`: a boolean value indicating that the build should be ready for deployment. When this option is added, options are not loaded from `medusa-config.js` anymore, and it means the admin will be built to be hosted on an external host. This also means that the backend URL is loaded from the `MEDUSA_ADMIN_BACKEND_URL` environment variable. For example, `medusa-admin build --deployment`. - -### Dev Command Options - -The `develop` command in the admin CLI allows you to run the admin dashboard in development separately from the Medusa backend. If you intend to use it, you should typically add it to the `package.json` of the Medusa backend: - -```json title="package.json" -{ - "scripts": { - // other scripts... - "dev:admin": "medusa-admin develop" - } -} -``` - -You can add the following options to the `medusa-admin dev` command: - -- `--backend` or `-b`: a string specifying the URL of the Medusa backend. By default, it's the value of the environment variable `MEDUSA_ADMIN_BACKEND_URL`. For example, `medusa-admin dev --backend example.com`. -- `--port` or `-p`: the port to run the admin on. By default, it's `7001`. For example, `medusa-admin dev --port 8000`. - ---- - -## Custom Environment Variables - -If you want to set environment variables that you want to access in your admin dashboard's customizations (such as in [widgets](./widgets.md) or [UI routes](./routes.md)), your environment variables must be prefixed with `MEDUSA_ADMIN_`. Otherwise, it won't be loaded within the admin. - -For example: - -```bash -MEDUSA_ADMIN_CUSTOM_API_KEY=123... -``` - ---- - -## Custom Webpack Configurations - -:::note - -Plugins cannot include webpack customizations. - -::: - -The admin dashboard uses [Webpack](https://webpack.js.org/) to define the necessary configurations for both the core admin plugin and your extensions. So, for example, everything works out of the box with Tailwind CSS, the admin dependencies, and more. - -However, you may have some advanced case where you need to tweak the webpack configurations. For example, you want to support styling your extensions with CSS Modules. - -For such use cases, you can extend the default webpack configurations defined in the admin plugin to add your custom configurations. - -To do that, create the file `src/admin/webpack.config.js` that uses the `withCustomWebpackConfig` method imported from `@medusajs/admin` to export the extended configurations. The method accepts a callback function that must return an object of [webpack configuration](https://webpack.js.org/configuration/). The callback function accepts two parameters: - -1. `config`: the first parameter is an object that holds the default webpack configuration. You should add your configurations to this object, then return it. Not returning the default configurations will lead to the application breaking. -2. `webpack`: the second parameter is the webpack instance. - -:::warning - -This is an advanced feature and requires knowledge of configuring webpack. If configured wrongly, it may lead to the admin application breaking. - -::: - -For example: - -```js title="src/admin/webpack.config.js" -import { withCustomWebpackConfig } from "@medusajs/admin" - -export default withCustomWebpackConfig((config, webpack) => { - config.plugins.push( - new webpack.DefinePlugin({ - "process.env": { - NODE_ENV: JSON.stringify("production"), - API_URL: - JSON.stringify("https://api.medusa-commerce.com"), - }, - }) - ) - - return config -}) -``` diff --git a/www/apps/docs/content/admin/configuration.mdx b/www/apps/docs/content/admin/configuration.mdx new file mode 100644 index 0000000000..06d3da9231 --- /dev/null +++ b/www/apps/docs/content/admin/configuration.mdx @@ -0,0 +1,337 @@ +--- +description: "In this document, you'll learn about the different ways you can configure the admin dashboard." +--- + +import ParameterTypes from "@site/src/components/ParameterTypes" + +# Admin Configuration + +In this document, you'll learn about the different ways you can configure the admin dashboard. + +## Plugin Options + +The plugin accepts the following options: + +```js title=medusa-config.js +const plugins = [ + // ... + { + resolve: "@medusajs/admin", + /** @type {import('@medusajs/admin').PluginOptions} */ + options: { + serve: true, + autoRebuild: true, + backend: "https://example.com", + path: "/app", + outDir: "build", + develop: { + open: true, + port: 7001, + logLevel: "error", + stats: "normal", + allowedHosts: "auto", + webSocketURL: undefined, + }, + }, + }, +] +``` + + + +--- + +## Admin CLI + +### Build Command Options + +The `build` command in the admin CLI allows you to manually build the admin dashboard. If you intend to use it, you should typically add it to the `package.json` of the Medusa backend: + +```json title="package.json" +{ + "scripts": { + // other scripts... + "build:admin": "medusa-admin build" + } +} +``` + +You can add the following option to the `medusa-admin build` command: + +- `--deployment`: a boolean value indicating that the build should be ready for deployment. When this option is added, options are not loaded from `medusa-config.js` anymore, and it means the admin will be built to be hosted on an external host. This also means that the backend URL is loaded from the `MEDUSA_ADMIN_BACKEND_URL` environment variable. For example, `medusa-admin build --deployment`. + +### Develop Command Options + +The `develop` command in the admin CLI allows you to run the admin dashboard in development separately from the Medusa backend. If you intend to use it, you should typically add it to the `package.json` of the Medusa backend: + +```json title="package.json" +{ + "scripts": { + // other scripts... + "dev:admin": "medusa-admin develop" + } +} +``` + +You can add the following options to the `medusa-admin develop` command: + +- `--backend` or `-b`: a string specifying the URL of the Medusa backend. By default, it's the value of the environment variable `MEDUSA_ADMIN_BACKEND_URL`. For example, `medusa-admin develop --backend example.com`. +- `--port` or `-p`: the port to run the admin on. By default, it's `7001`. For example, `medusa-admin develop --port 8000`. + +--- + +## Change Backend URL + +### In Development + +To change the backend's URL that the admin sends request to in development, you must disable the `serve` plugin option and set the `backend` option to the URL of your Medusa backend. + +However, this requires you to also set-up the [develop command](#develop-command-options) as the admin will no longer start with the Medusa backend. + +For example: + +```js title=medusa-config.js +const plugins = [ + // ... + { + resolve: "@medusajs/admin", + /** @type {import('@medusajs/admin').PluginOptions} */ + options: { + serve: false, + backend: "http://localhost:9001", + // other options... + }, + }, +] +``` + +### In Production + +:::note + +This assumes that you've deployed the admin separately and you're passing the `--deployment` option to the [build command](#build-command-options). + +::: + +To change the backend's URL that the admin sends request to in production, set the environment variable `MEDUSA_ADMIN_BACKEND_URL` to the backend's URL. + +For example: + +```bash +MEDUSA_ADMIN_BACKEND_URL=https://example.com +``` + +--- + +## Custom Environment Variables + +If you want to set environment variables that you want to access in your admin dashboard's customizations (such as in [widgets](./widgets.md) or [UI routes](./routes.md)), your environment variables must be prefixed with `MEDUSA_ADMIN_`. Otherwise, it won't be loaded within the admin. + +For example: + +```bash +MEDUSA_ADMIN_CUSTOM_API_KEY=123... +``` + +--- + +## Custom Webpack Configurations + +:::note + +Plugins cannot include webpack customizations. + +::: + +The admin dashboard uses [Webpack](https://webpack.js.org/) to define the necessary configurations for both the core admin plugin and your extensions. So, for example, everything works out of the box with Tailwind CSS, the admin dependencies, and more. + +However, you may have some advanced case where you need to tweak the webpack configurations. For example, you want to support styling your extensions with CSS Modules. + +For such use cases, you can extend the default webpack configurations defined in the admin plugin to add your custom configurations. + +To do that, create the file `src/admin/webpack.config.js` that uses the `withCustomWebpackConfig` method imported from `@medusajs/admin` to export the extended configurations. The method accepts a callback function that must return an object of [webpack configuration](https://webpack.js.org/configuration/). The callback function accepts two parameters: + +1. `config`: the first parameter is an object that holds the default webpack configuration. You should add your configurations to this object, then return it. Not returning the default configurations will lead to the application breaking. +2. `webpack`: the second parameter is the webpack instance. + +:::warning + +This is an advanced feature and requires knowledge of configuring webpack. If configured wrongly, it may lead to the admin application breaking. + +::: + +For example: + +```js title="src/admin/webpack.config.js" +import { withCustomWebpackConfig } from "@medusajs/admin" + +export default withCustomWebpackConfig((config, webpack) => { + config.plugins.push( + new webpack.DefinePlugin({ + "process.env": { + NODE_ENV: JSON.stringify("production"), + API_URL: + JSON.stringify("https://api.medusa-commerce.com"), + }, + }) + ) + + return config +}) +``` diff --git a/www/apps/docs/content/admin/quickstart.mdx b/www/apps/docs/content/admin/quickstart.mdx index 28075829bb..464f0a7081 100644 --- a/www/apps/docs/content/admin/quickstart.mdx +++ b/www/apps/docs/content/admin/quickstart.mdx @@ -69,28 +69,10 @@ const plugins = [ ] ``` -The plugin accepts the following options: - -1. `serve`: (default: `true`) a boolean indicating whether to serve the admin dashboard when the Medusa backend starts. If set to `false`, you can serve the admin dashboard using the [dev command](./configuration.md#dev-command-options). -2. `path`: (default: `app`) a string indicating the path the admin server should run on when running the Medusa backend in production. It must be prefixed with a slash `/`, but it can't end with a `/`, which throws an error. It also can't be one of the reserved paths: "admin" and "store". -3. `outDir`: Optional path for where to output the admin build files. -4. `autoRebuild`: (default: `false`) a boolean indicating whether the admin UI should be rebuilt if there are any changes or if a missing build is detected when the backend starts. If not set, you must [manually build the admin dashboard](./configuration.md#build-command-options). -5. `develop`: An optional object that accepts the following properties: - - `open`: (default: `true`) a boolean value that indicates if the browser should be opened when the medusa project is first started. - - `port`: (default: `7001`) a number indicating the port the admin dashboard runs on. - -### Optional: Manually Building Admin Dashboard - -If you have `autoRebuild` disabled, you must build your admin dashboard before starting the Medusa backend. Refer to the [build command](./configuration.md#build-command-options) for more details. +Check [this documentation](./configuration.mdx#plugin-options) for a full list of available options. ### Step 3: Test the Admin Dashboard -:::tip - -If you disabled the `serve` option, you need to run the admin dashboard separately using the [dev command](./configuration.md#dev-command-options) - -::: - You can test the admin dashboard by running the following command in the directory of the Medusa backend: ```bash @@ -112,14 +94,14 @@ This starts the Medusa Backend and the admin dashboard in a development environm :::note -This doesn't apply if you have the `serve` option disabled. +This doesn't apply if you have the `serve` option disabled or you're deploying the admin separately. ::: When you run the Medusa project in a production environment (such as with the `npx medusa start` command), the admin dashboard will be available at `/`, where: 1. `` is the URL of your Medusa backend. By default, it'll be `localhost:9000` locally. -2. `` is the path you define in the [admin's configurations](#step-2-add-admin-to-medusa-configurations). +2. `` is the path you define in the [admin plugin's configurations](./configuration.mdx#plugin-options). So, if you simulate a production environment locally, the admin dashboard will run by default on `localhost:9000/app`. @@ -196,6 +178,6 @@ Can't find your language? Learn how you can contribute by translating the admin ## See Also -- [Admin Configuration](./configuration.md) +- [Admin Configuration](./configuration.mdx) - [Admin widgets](./widgets.md) - [Admin UI routes](./routes.md) diff --git a/www/apps/docs/content/create-medusa-app.mdx b/www/apps/docs/content/create-medusa-app.mdx index f3de6fed2b..32758f7647 100644 --- a/www/apps/docs/content/create-medusa-app.mdx +++ b/www/apps/docs/content/create-medusa-app.mdx @@ -18,7 +18,7 @@ import EaddrinuseSection from './troubleshooting/eaddrinuse.md' import InvalidTokenError from './troubleshooting/create-medusa-app-errors/_no-browser-token-error.md' import PostgresDockerError from './troubleshooting/database-errors/_docker.md' import DbUrlError from './troubleshooting/create-medusa-app-errors/_db-url-error.md' -import PortError from './troubleshooting/create-medusa-app-errors/_port.md' +import ForwardingError from './troubleshooting/create-medusa-app-errors/_forwarding.md' # Install Medusa with create-medusa-app @@ -220,8 +220,8 @@ Based on what you're building, you can find a development path for you in the Re + title: "Errors when using VSCode or GitHub Codespaces", + content: }, { title: 'Can\'t connect to database with --db-url option', diff --git a/www/apps/docs/content/deployments/server/deploying-on-digital-ocean.md b/www/apps/docs/content/deployments/server/deploying-on-digital-ocean.md index 0c5dd73418..b6e0071504 100644 --- a/www/apps/docs/content/deployments/server/deploying-on-digital-ocean.md +++ b/www/apps/docs/content/deployments/server/deploying-on-digital-ocean.md @@ -282,7 +282,7 @@ You can access `/health` to get health status of your deployed backend. :::note -Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.md#build-command-options) command as part of the start command of your backend. +Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.mdx#build-command-options) command as part of the start command of your backend. ::: diff --git a/www/apps/docs/content/deployments/server/deploying-on-heroku.mdx b/www/apps/docs/content/deployments/server/deploying-on-heroku.mdx index 18bddb2744..d2ac51c04e 100644 --- a/www/apps/docs/content/deployments/server/deploying-on-heroku.mdx +++ b/www/apps/docs/content/deployments/server/deploying-on-heroku.mdx @@ -250,7 +250,7 @@ You can access `/health` to get health status of your deployed backend. :::note -Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.md#build-command-options) command as part of the `serve` command of your backend. +Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.mdx#build-command-options) command as part of the `serve` command of your backend. ::: diff --git a/www/apps/docs/content/deployments/server/deploying-on-microtica.md b/www/apps/docs/content/deployments/server/deploying-on-microtica.md index e3af825c88..43bceaf406 100644 --- a/www/apps/docs/content/deployments/server/deploying-on-microtica.md +++ b/www/apps/docs/content/deployments/server/deploying-on-microtica.md @@ -110,7 +110,7 @@ You can access `/health` to get health status of your deployed backend. :::note -Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.md#build-command-options) command as part of the start command of your backend. +Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.mdx#build-command-options) command as part of the start command of your backend. ::: diff --git a/www/apps/docs/content/deployments/server/deploying-on-railway.md b/www/apps/docs/content/deployments/server/deploying-on-railway.md index 47840ba401..33b9f50220 100644 --- a/www/apps/docs/content/deployments/server/deploying-on-railway.md +++ b/www/apps/docs/content/deployments/server/deploying-on-railway.md @@ -221,7 +221,7 @@ You can access `/health` to get health status of your deployed backend. :::note -Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.md#build-command-options) command as part of the start command of your backend. +Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.mdx#build-command-options) command as part of the start command of your backend. ::: diff --git a/www/apps/docs/content/development/entities/extend-repository.md b/www/apps/docs/content/development/entities/extend-repository.md index a99b58ffb3..99946a4da0 100644 --- a/www/apps/docs/content/development/entities/extend-repository.md +++ b/www/apps/docs/content/development/entities/extend-repository.md @@ -54,7 +54,9 @@ export const ProductRepository = dataSource .extend({ // it is important to spread the existing repository here. // Otherwise you will end up losing core properties - ...Object.assign(MedusaProductRepository, { target: Product }), + ...Object.assign(MedusaProductRepository, { + target: Product, + }), /** * Here you can create your custom function diff --git a/www/apps/docs/content/troubleshooting/cors-issues.md b/www/apps/docs/content/troubleshooting/cors-issues.md index de9122e9ed..c6fcb7afe0 100644 --- a/www/apps/docs/content/troubleshooting/cors-issues.md +++ b/www/apps/docs/content/troubleshooting/cors-issues.md @@ -8,7 +8,7 @@ You might see a log in your browser console, that looks like this: ![CORS error log](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003322/Medusa%20Docs/Other/jnHK115_udgf2n.png) -In your `medusa-config.js` , you should ensure that you've configured your CORS settings correctly. By default, the Medusa starter runs on port `9000`, Medusa Admin runs on port `7000`, and the storefront starters run on port `8000`. +In your `medusa-config.js` , you should ensure that you've configured your CORS settings correctly. By default, the Medusa starter runs on port `9000`, Medusa Admin runs on port `7001`, and the storefront starters run on port `8000`. The default configuration uses the following CORS settings: diff --git a/www/apps/docs/content/troubleshooting/create-medusa-app-errors.mdx b/www/apps/docs/content/troubleshooting/create-medusa-app-errors.mdx index 3b7858fa8c..081417e191 100644 --- a/www/apps/docs/content/troubleshooting/create-medusa-app-errors.mdx +++ b/www/apps/docs/content/troubleshooting/create-medusa-app-errors.mdx @@ -7,7 +7,7 @@ import OtherErrors from './create-medusa-app-errors/_other-errors.mdx' import InvalidTokenError from './create-medusa-app-errors/_no-browser-token-error.md' import DockerSection from "./database-errors/_docker.md" import DbUrlError from './create-medusa-app-errors/_db-url-error.md' -import PortError from './create-medusa-app-errors/_port.md' +import ForwardingError from './create-medusa-app-errors/_forwarding.md' ## TypeError: cmd is not a function @@ -15,9 +15,9 @@ import PortError from './create-medusa-app-errors/_port.md' --- -## Admin Login or User Errors +## Errors when using VSCode or GitHub Codespaces - + --- diff --git a/www/apps/docs/content/troubleshooting/create-medusa-app-errors/_forwarding.md b/www/apps/docs/content/troubleshooting/create-medusa-app-errors/_forwarding.md new file mode 100644 index 0000000000..c6290d3861 --- /dev/null +++ b/www/apps/docs/content/troubleshooting/create-medusa-app-errors/_forwarding.md @@ -0,0 +1,13 @@ +If you're running the Medusa backend through tools like VSCode or GitHub Codespaces, you must ensure that: + +1. Port forwarding is configured for ports `9000` and `7001`. Refer to the following resources on how to configure forwarded ports: + 1. [VSCode local development.](https://code.visualstudio.com/docs/editor/port-forwarding) + 2. [VSCode remote development.](https://code.visualstudio.com/docs/remote/ssh#_forwarding-a-port-creating-ssh-tunnel) + 3. [GitHub Codespaces.](https://docs.github.com/en/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace) +2. If your tool or IDE exposes an address other than `localhost`, such as `127.0.0.1`, make sure to add that address to the [admin_cors](../../development/backend/configurations.md#admin_cors-and-store_cors) Medusa configuration. Your tool will show you what the forwarded address is. + +After setting these configurations, run your Medusa backend and try again. If you couldn't create an admin user before, run the following command in the root directory of your Medusa project to create an admin user: + +```bash +npx medusa user -e admin@medusa-test.com -p supersecret +``` diff --git a/www/apps/docs/content/troubleshooting/create-medusa-app-errors/_port.md b/www/apps/docs/content/troubleshooting/create-medusa-app-errors/_port.md deleted file mode 100644 index 99a346d4a8..0000000000 --- a/www/apps/docs/content/troubleshooting/create-medusa-app-errors/_port.md +++ /dev/null @@ -1,10 +0,0 @@ -By default, the Medusa backend runs on `localhost:9000`. However, the port may change based on the `PORT` environment variable. - -If you run the `create-medusa-app` command, and the installation finishes successfully, but the backend runs on a different port than `9000`, it may cause errors when you try to create an admin user or login during the onboarding process. This could either be because you have the `PORT` environment variable set to something differnt, or because of port forwarding. - -To resolve this, you must: - -1. Terminate the `create-medusa-app` process and change to the new backend's directory. -2. Either explicitely set the `PORT` environment variable to `9000`, or set the environment variable `MEDUSA_ADMIN_BACKEND_URL` to the backend's URL. For example, if the backend is running on `localhost:7000`, change the `MEDUSA_ADMIN_BACKEND_URL` to `http://localhost:7001`. This ensures that the admin uses the correct port. In case of port fowarding, it's recommended to explicitely set the `PORT` environment variable. -3. Create an admin user using the [user command of the CLI tool](../../cli/reference.mdx#user). -4. Start the backend again either with the `dev` command of the backend project or using `npx medusa develop` and try to login again. diff --git a/www/apps/docs/content/troubleshooting/eaddrinuse.md b/www/apps/docs/content/troubleshooting/eaddrinuse.md index 99cace4f49..9bbbe937c9 100644 --- a/www/apps/docs/content/troubleshooting/eaddrinuse.md +++ b/www/apps/docs/content/troubleshooting/eaddrinuse.md @@ -14,5 +14,5 @@ port: 9000 This means that there's another process running at port `9000`. You need to either: -- Change the default port used by the Medusa backend. You can do that by setting the `PORT` environment variable to a new port. When you do this, make sure to change the port used in other apps that interact with your Medusa backend, such as in your [admin](../admin/configuration.md#build-command-options) or [storefront](../starters/nextjs-medusa-starter.mdx#changing-medusa-backend-url). +- Change the default port used by the Medusa backend. You can do that by setting the `PORT` environment variable to a new port. When you do this, make sure to change the port used in other apps that interact with your Medusa backend, such as in your [admin](../admin/configuration.mdx#build-command-options) or [storefront](../starters/nextjs-medusa-starter.mdx#changing-medusa-backend-url). - Terminate other processes running on port `9000`. diff --git a/www/apps/docs/sidebars.js b/www/apps/docs/sidebars.js index 04523e9a69..f3231e1c49 100644 --- a/www/apps/docs/sidebars.js +++ b/www/apps/docs/sidebars.js @@ -187,7 +187,7 @@ module.exports = { items: [ { type: "doc", - label: "Admin Custom Configuration", + label: "Admin Configuration", id: "admin/configuration", }, {