feat(admin): Improve DX for deploying admin externally

[kasperkristensen]

What

• Updates the args that can be passed to medusa-admin build.

Argument	Description	Type	Flag
deployment	If true we do not attempt to load options from medusa.config.js. This flag indicates that we are using @medusajs/admin as a build tool, to build and host our UI with an external host (e.g. Vercel)	boolean	--deployment
backend	Specified a URL to your Medusa server (defaults to env variable MEDUSA_BACKEND_URL)	string	-b, --backend
outDir	Custom path to output the build files to (defaults to build)	string	-o, --out-dir
include	Path to files that you want to include in the build output, this can be used to inject a file that your host of choice may need. An example could be the 200.html file needed for redirects when hosting on Surge.	string[]	-i, --include
includeDir	Used to specify where to copy included files too, this can be used if the files you are copying need to be copied to a destination other than the root of the build directory.	string	-d, --include-dist

• Updates the default behavior when using the plugin to serve the UI
  • Auto rebuilds based on config changes are disabled by default, in order for users to enable the feature they should add it to their plugin options:

{
  resolve: "@medusajs/admin",
  options: {
    autoRebuild: true,
  }
}

• Simplifies options available in plugin options. Since users should only install the plugin as a direct dependency, and add it to their medusa.config.js when serving the UI, all options related to building for deployment has been removed, and can only be passed as command arguments.

  • The available options are serve?: boolean = true, path?: string = "app", outDir?: string = "build", and autoRebuild?: boolean = false.

• Adds a dev command that can be used to spin up a developer instance of the UI - medusa-admin dev.

  • Accepts two arguments -p, --port <port> (default 7001) and -b, --backend <backend> (default "http://localhost:9000")
  • The command has no real use at the moment for users as they should simply always build their UI, but will be used when we support extensions so developers won't have to rebuild constantly while developing their plugin UI.

• Adds a new eject command that can be used to eject the source code of the Admin UI - medusa-admin eject -o admin. This command is useful in two cases:

  • The user wants to host the admin UI with a provider that only supports deployments using a CLI tool, which needs to run commands against the source code (e.g. Firebase).
  • The user wants to use our Admin as a starting point for building their own. This command allows them to receive a repo where dependencies, Tailwind, and Vite is set up as it is in our current Admin repo, and allows them to easily start making the changes they want to.

Examples of how to use the plugin

Here are a couple of examples of setups with the plugin.

Deployment to Vercel

When a user wishes to deploy the UI to an external host like Vercel, the plugin should be installed as a devDependency, as we don't want to inject any API and startup logic.

Install the plugin

yarn add -D @medusajs/admin

Add a build script to package.json

"scripts": {
  "build:admin": "medusa-admin build --deployment",
}

Add a vercel.json file at the root of your server directory

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

Push your changes to GitHub

git add .
git commit -m "prepare repository for deployment"
git push

Setup Vercel to deploy the admin UI

Note that Vercel (and any other hosting platform) won't be able to auto-detect that we are using Vite, so you need to manually select it as the Framework Preset.

Serving the UI from the server

When serving the UI from the server the plugin should be installed as a direct dependency.

Install the plugin

yarn add @medusajs/admin

Add plugin to plugins in medusa.config.js

Using the default options:

// This is the place to include plugins. See API documentation for a thorough guide on plugins.
const plugins = [
  `medusa-fulfillment-manual`,
  `medusa-payment-manual`,
  {
    resolve: `medusa-payment-stripe`,
    options: {
      api_key: STRIPE_API_KEY,
      webhook_secret: STRIPE_WEBHOOK_SECRET,
    },
  },
  "@medusajs/admin",
];

Using custom options:

{
    resolve: "@medusajs/admin",
    /** @type {import('@medusajs/admin').PluginOptions} */
    options: {
      autoRebuild: true,
      path: "dashboard",
    },
  },

Deciding on how to build the UI

The plugin offers two approaches for how to build the admin UI: manually using the CLI and automatically as part of the server startup.

The latter options will look for changes to your plugin options and check if a build file is missing for the admin UI on each server start. If the options have changed, or the plugin is unable to locate a build output for the admin UI it will automatically build the project before the server is started. This is very practical, as you can set it and forget it and be sure that the admin UI will always be built and ready before your server is started. It does however have one major drawback, as the build step is a memory-intensive process. In order for this to work in a production setup your server will need a min. 2GB-4GB of RAM, otherwise, it will throw a heap out-of-memory error on startup. If you wish to make use of the auto-rebuild feature, you will need to enable it in your plugin options:

{
    resolve: "@medusajs/admin",
    /** @type {import('@medusajs/admin').PluginOptions} */
    options: {
      autoRebuild: true,
    },
  },

If you are working with a less powerful setup, you will need to handle building the admin UI yourself. The most straightforward approach is to simply run medusa-admin build from your terminal before you deploy your server. The process can be improved quite a bit using tools such as GitHub actions to automate building the UI with out it taking a toll on the memory resources of your server. Here is an example of how you can setup a GitHub action to build the UI before pushing your server to be hosted on Heroku:

In your package.json add a new script to build the admin UI

"scripts": {
  "build:admin": "medusa-admin build",
}

Add a new .yml file to your .github/workflows folder

name: Deploy server with admin

on:
  push:
    branches:
      - main
    paths-ignore:
      - ".github/**"
  workflow_dispatch:


jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    steps:
      - name: Cancel Previous Runs
        uses: styfle/[email protected]
        with:
          access_token: ${{ github.token }}

      - name: Setup Node.js 16.x
        uses: actions/setup-node@v2
        with:
          node-version: 16.x
          
      - name: Checkout
        uses: actions/[email protected]

      - name: install dependencies
        run: yarn install

      - name: build admin ui
        run: yarn build:admin
          
      - uses: akhileshns/[email protected] 
        with:
          heroku_api_key: ${{secrets.HEROKU_API_KEY}}
          heroku_app_name: ${{secrets.HEROKU_APP_NAME}}
          heroku_email: ${{secrets.HEROKU_EMAIL}}

cc: @shahednasser I've added some examples to the description on how to set up the plugin that we can use for the documentation when we get there ✌️

[changeset-bot]

🦋 Changeset detected

Latest commit: 95e3db4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@medusajs/admin-ui	Patch
@medusajs/admin	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated
medusa-docs	✅ Ready (Inspect)	Visit Preview	💬 Add your feedback	Mar 17, 2023 at 10:28AM (UTC)

[kasperkristensen]

/snapshot-this

[github-actions]

🚀 A snapshot release has been made for this PR

Test the snapshots by updating your package.json with the newly published versions:

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add @medusajs/[email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

Latest commit: f0a1355

[kasperkristensen]

/snapshot-this

[github-actions]

🚀 A snapshot release has been made for this PR

Test the snapshots by updating your package.json with the newly published versions:

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add @medusajs/[email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add [email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

yarn add @medusajs/[email protected]

Latest commit: f0a1355

[olivermrbl]

Should the admin build itself, with the simplest config, on the first server start?

Sorry if you've mentioned this somewhere; I tried to look for it in the PR description, but couldn't find it (maybe in the last PR?)

So doing:

yarn add @medusajs/admin@

and adding

const plugins = [ "medusajs/admin" ]

On first server start, this gives me a build folder with an empty index.html.

Though, if I build the admin using the CLI and restart, everything works as expected.

[olivermrbl]

Also, because the index.html exists, we pass through this check. Maybe we should add a check for an empty file?

[olivermrbl]

Love this! Added a couple of comments, that I'd like you to address before we merge :)

[kasperkristensen]

@olivermrbl It is not meant to build the project with the default options automatically. Users must enable it with "autoRebuild": true in the options. I was mistakenly creating an empty index file as part of the check to see if it existed, I've fixed that so we now throw an error without creating an empty file.

[olivermrbl]

Works - great one 💪