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

docs: documentation changes for release (#4300)

Browse Source 
* docs: added manage reservations user guide (#4290)

* docs: added manage reservations user guide

* removed feature flag details

* docs: added how-to for custom reservations (#4292)

* docs: added how-to for custom reservations

* eslint fixes

* docs: added product module documentation (#4287)

* docs: added product module documentation

* added details about optional environment variables

* small fixes

* Remove reference link

* added example usages

* added link to sample project

* address PR feedback

* docs: moved product module guide + added product module tabs (#4307)

* added product module tab

* adjust design of badge

* docs: added onboarding features (#4168)

* added marketplace page

* added subscription roadmap

* added rating for onboarding

* added learning path components

* small fixes

* fix build error

* fix eslint errors

* change roadmaps to recipes

* small change in text

* optimize learning path and notifications

* fix tracking usage

* fix eslint errors

* added enter/exit animation

* allow starting a path using a query parameter

* fix gap between notifications

* address vercel comments

* fixed links issue

* changed create-medusa-app docs steps

* move troubleshooting section

* improved tracking across docs

* fix build errors

* remove console

* added a note about `boilerplate` option

* added troubleshooting section for eagain

* added invite option in cli reference

* added track event for finished onboarding

* update boilerplate option name

* redesigned learning path component

* docs: added how to create widget docs (#4318)

* docs: added how to create widget docs

* remove development guide

* added types

* docs: added details about createCustomAdminHooks (#4288)

* docs: added details about createCustomAdminHooks

* small improvement

* added missing import

* small changes

* docs: added onboarding guide (#4320)

* docs: added how to create widget docs

* remove development guide

* docs: added onboarding guide

* added types

* added recipes link

* small adjustments

* fixed eslint errors

* styling fixes

* change to singular product module

* updated the what's new section

* shorten down medusa react card

* updated tailwind configurations

* fix build error

* fix newspaper icon

* style fixes

* change modal shadow

* fix color of line numbers

* fix code fade color

* docs: updated admin documentations

* eslint fixes

* text changes

* added a note about beta version

* remove empty object argument

* remove demo repo url

* fix selection color for code headers

* general fixes

* fix eslint error

* changed code theme

* added preparation step

* changes regarding beta version

* Update docs/content/modules/products/serverless-module.md

Co-authored-by: Riqwan Thamir <rmthamir@gmail.com>

* Update docs/content/modules/products/serverless-module.md

Co-authored-by: Riqwan Thamir <rmthamir@gmail.com>

---------

Co-authored-by: Riqwan Thamir <rmthamir@gmail.com>
Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com>
This commit is contained in:
Shahed Nasser
2023-06-20 13:25:22 +03:00
committed by GitHub
parent 8db03619b5
commit 76c4bf4acb
177 changed files with 8828 additions and 1196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
docs/content/admin/development.md
View File

@@ -1,111 +0,0 @@
---
description: 'Learn how to set up the Medusa Admin repository for local development and customization. This includes cloning the GitHub repository and adding an upstream repository.'
addHowToData: true
---
# Customize Medusa Admin
In this document, you’ll learn how to customize the Medusa admin by forking it, and how to keep it updated with changes from the main repository.
:::warning
This guide explains how to customize the Medusa Admin repository, which is now deprecated. This guide doesn't work with the [admin plugin](./quickstart.mdx).
:::
## Overview
Although Medusa provides an intuitive admin that should cover all your ecommerce needs, you are free to customize the Medusa admin as you see fit.
For customization and development, it’s recommended that you fork the main Medusa admin repository. That way, you can configure your forked repository to pull changes from the main Medusa admin repository for any latest updates.
In this document, you’ll learn how to:
- Fork the Medusa admin repository.
- Configure the Medusa admin repository as an upstream repository.
- Pull changes from the upstream repository to keep your fork synced with the Medusa admin repository.
---
## Prerequisites
### Required Tools
[Git CLI tool](../development/backend/prepare-environment.mdx#git)
### Required Accounts
[GitHub](https://github.com/)
---
## Fork the Medusa Admin Repository
To fork the Medusa admin:
1. Go to the [Medusa admin repository](https://github.com/medusajs/admin).
2. Click on the Fork button at the top right.
3. You can optionally change the name of the repository and description.
4. Once done, click on the Create fork button.
5. After your fork is created, you can clone it using the following command:
```bash
git clone <REPOSITORY_URL>
```
Where `<REPOSITORY_URL>` is the HTTPS URL of your repository. You can obtain it from your forked repository’s GitHub page by clicking on the Code button and copying the URL.
---
## Configure Upstream Repository
To configure the Medusa admin as the upstream repository:
1. Change to the directory of your cloned forked repository.
2. Run the following command to add the Medusa admin repository as an upstream repository:
```bash
git remote add upstream https://github.com/medusajs/admin
```
1. You can verify that it has been added by running the following command:
```bash
git remote -v
```
You should see an `origin` repository which is your forked repository, and an `upstream` repository which is the Medusa admin repository.
---
## Update your Fork with Latest Changes
To update your fork with the latest changes from the Medusa admin repository:
1. Change to the directory of your cloned forked repository.
2. Run the following command to fetch the latest changes from the Medusa admin repository:
```bash
git fetch upstream
```
1. Make sure you’re on your `main` or `master` branch of the forked repository:
```bash
git checkout main
```
1. Merge the changes from the `main` branch of the Medusa admin repository:
```bash
git merge upstream/main
```
If your forked repository doesn’t have any conflicts with the changes from the Medusa admin repository, the merge will be done successfully. Otherwise, you’ll need to [resolve these conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line).
---
## See Also
- [Admin API reference](/api/admin).
- [Local development with Medusa](../development/fundamentals/local-development.md).

2420
docs/content/admin/onboarding.md Normal file
View File

File diff suppressed because it is too large Load Diff

105
docs/content/admin/quickstart.mdx
View File

@@ -6,30 +6,18 @@ addHowToData: true
import Feedback from '@site/src/components/Feedback';
import Troubleshooting from '@site/src/components/Troubleshooting'
import AdminLoginSection from '../troubleshooting/signing-in-to-admin.md'
import CorsSection from '../troubleshooting/cors-issues.md'
# Admin Dashboard Quickstart
This document will guide you through setting up the admin dashboard in the Medusa backend.
:::note
The admin dashboard is now shipped as an NPM package, and the previous GitHub repository has been deprecated.
:::
## Overview
The admin dashboard is installed on the Medusa backend. The admin dashboard starts when you start the Medusa backend. This also means you can later deploy the Medusa backend along with the admin dashboard on the same hosting.
This guide will explain the steps and configurations required to set up the admin dashboard.
<!-- The admin dashboard is installed on the Medusa backend. Setting it up depends on how you intend to use it:
1. [Served alongside the Medusa backend](#option-1-install-and-serve-admin-with-the-backend): with this approach, the admin dashboard starts when you start the Medusa backend. This also means you can later deploy the Medusa backend along with the admin dashboard on the same hosting.
2. [Served separately from the Medusa backend](#option-2-install-and-serve-admin-separately): with this approach, the admin dashboard starts separately from the Medusa backend. You still need the Medusa backend to be running as the admin uses its APIs. This is useful if you intend to later deploy the admin dashboard on a different hosting than the Medusa Backend, such as using Vercel.
This guide will explain the steps and configurations required for both approaches. -->
---
## Prerequisites
@@ -52,20 +40,10 @@ You can install Node from the [official website](https://nodejs.org/en/).
---
<!-- ## Option 1: Install and Serve Admin with the Backend -->
## Install and Serve Admin with the Backend
This section explains how to install the admin to be served with the Medusa Backend and later deployed together.
<!-- :::note
If you decide later to serve the admin for development separately or deploy it on a different hosting, you can go back and follow the steps in [Option 2](#option-2-install-and-serve-admin-serparately).
:::
-->
### Step 1: Install the Package
In the directory of your Medusa backend, run the following command to install admin dashboard:
@@ -74,6 +52,16 @@ In the directory of your Medusa backend, run the following command to install ad
npm install @medusajs/admin
```
:::note
Installing the `@beta` version of the admin and Medusa core allows you to perform customizations such as creating [Admin Widgets](./widgets.md) or [Admin Dashboard Routes](./routes.md). You can install the `beta` version with the following command:
```bash npm2yarn
npm install @medusajs/admin@beta @medusajs/medusa@beta
```
:::
### Step 2: Add Admin to Medusa Configurations
In `medusa-config.js`, add the admin plugin into the array of `plugins`:
@@ -94,7 +82,7 @@ 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](#dev-command-options).
2. `path`: (default: `app`) a string indicating the path the admin server should run on. It shouldn't be prefixed or suffixed with a slash `/`, and it can't be one of the reserved paths: "admin" and "store".
2. `path`: (default: `app`) a string indicating the path the admin server should run on when [running the Medusa backend in production](#note-on-admin-path). It shouldn't be prefixed or suffixed with a slash `/`, and it 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](#build-command-options).
@@ -116,66 +104,14 @@ You can test the admin dashboard by running the following command in the directo
npx @medusajs/medusa-cli develop
```
This starts the Medusa Backend and the admin dashboard. By default, the admin will be available on the URL `localhost:9000/app`. If you set the `path` option, then the admin will be available on `localhost:9000/<PATH>` with `<PATH>` being the value of the `path` option.
<Feedback
event="survey_admin_quickstart"
question="Did you set up the admin successfully?"
positiveQuestion="Is there anything that should improved?"
negativeQuestion="Please describe the issue you faced."
/>
---
<!--
## Option 2: Install and Serve Admin Separately
This section explains how to install the admin dashboard using approach 2, which allows you to serve and later deploy the admin separately.
This starts the Medusa Backend and the admin dashboard. By default, the admin will be available on the URL `localhost:9000/app`. If you set the path option, then the admin will be available on `localhost:9000/<PATH>` with `<PATH>` being the value of the path option.
:::note
If you decide later to serve and deploy the admin alongside the server, you can go back and follow the steps in [Option 1](#option-1-install-and-serve-admin-with-the-backend).
If you're using the `@beta` version of the admin plugin, the admin dashboard will run on `localhost:7001` when you run the `develop` command.
:::
### Step 1: Install the Package
In the directory of your Medusa backend, run the following command to install admin dashboard:
```bash npm2yarn
npm install @medusajs/admin --save-dev
```
### Step 2: Add Scripts to Package.json
Add the following scripts to `package.json` in the directory of the Medusa backend:
```json title=package.json
{
"scripts": {
// other scripts...
"build:admin": "medusa-admin build",
"dev:admin": "medusa-admin dev"
}
}
```
Where:
- `build:admin`: Used to manually create a build of the admin. In this approach, it's useful with the `--deployment` option to build the admin for deployment. You can learn more about all available options in [this section](#build-command-options).
- `dev:admin`: Used to run the development server of the admin. You can learn about other available options for this command in [this section](#dev-command-options).
### Step 3: Start Admin in Development
Make sure to run the Medusa backend first. Then, in the root directory of the backend, run the following command to start the admin development server:
```bash npm2yarn
npm run dev:admin
```
This runs the admin dashboard on `localhost:7001`.
<Feedback
event="survey_admin_quickstart"
question="Did you set up the admin successfully?"
@@ -185,8 +121,6 @@ This runs the admin dashboard on `localhost:7001`.
---
-->
## Demo Credentials
If you installed the demo data when you installed the Medusa backend by running:
@@ -276,5 +210,16 @@ You can learn more about the admin dashboard and its features in the [User Guide
title: 'Signing into Admin',
content: <AdminLoginSection />
},
{
title: 'CORS Errors',
content: <CorsSection />
}
]}
/>
---
## See Also
- [Admin widgets](./widgets.md)
- [Admin UI routes](./routes.md)

326
docs/content/admin/routes.md Normal file
View File

@@ -0,0 +1,326 @@
---
title: 'How to Create an Admin UI Route'
description: 'Learn how to create a new route in the admin dashboard.'
addHowToData: true
badge:
variant: orange
text: beta
---
In this document, you’ll learn how to create a new route in the admin dashboard.
## Overview
You can customize the admin dashboard that Medusa provides to add new routes. This is useful if you want to add new subpages to the admin dashboard, or you want to add new pages that appear in the sidebar as well.
An admin UI route is essentially a React Component created under the `src/admin/routes` directory.
This guide explains how to create a new route in the admin dashboard with some examples.
---
## Prerequisites
It’s assumed you already have a Medusa backend with the admin plugin installed before you move forward with this guide. If not, you can follow [this documentation page](../create-medusa-app.mdx) to install a Medusa project.
Furthermore, Admin UI Routes are currently available as a beta feature. So, you must install the `beta` version of the `@medusajs/admin` and `@medusajs/medusa` packages:
```bash npm2yarn
npm install @medusajs/admin@beta @medusajs/medusa@beta
```
### (Optional) TypeScript Preparations
Since routes are React components, they should be written in `.tsx` or `.jsx` files. If you’re using Typescript, you need to make some adjustments to avoid Typescript errors in your Admin files.
This section provides recommended configurations to avoid any TypeScript errors.
:::note
These changes may already be available in your Medusa project. They're included here for reference purposes.
:::
First, update your `tsconfig.json` with the following configurations:
```json title=tsconfig.json
{
"compilerOptions": {
"target": "es2019",
"module": "commonjs",
"allowJs": true,
"checkJs": false,
"jsx": "react-jsx",
"declaration": true,
"outDir": "./dist",
"rootDir": "./src",
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"noEmit": false,
"strict": false,
"moduleResolution": "node",
"esModuleInterop": true,
"resolveJsonModule": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/"],
"exclude": [
"dist",
"build",
".cache",
"tests",
"**/*.spec.js",
"**/*.spec.ts",
"node_modules",
".eslintrc.js"
]
}
```
The important changes to note here are the inclusion of the field `"jsx": "react-jsx"` and the addition of `"build"` and `“.cache”` to `exclude`.
The addition of `"jsx": "react-jsx"` specified how should TypeScript transform JSX, and excluding `build` and `.cache` ensures that TypeScript ignores build and development files.
Next, create the file `tsconfig.server.json` with the following content:
```json title=tsconfig.server.json
{
"extends": "./tsconfig.json",
"compilerOptions": {
/* Emit a single file with source maps instead of having a separate file. */
"inlineSourceMap": true
},
"exclude": ["src/admin", "**/*.spec.js"]
}
```
This is the configuration that will be used to transpile your custom backend code, such as services or entities. The important part is that it excludes `src/admin` as that is where your Admin code will live.
Finally, create the file `tsconfig.admin.json` with the following content:
```json title=tsconfig.admin.json
{
"extends": "./tsconfig.json",
"compilerOptions": {
"module": "esnext"
},
"include": ["src/admin"],
"exclude": ["**/*.spec.js"]
}
```
This is the configuration that will be used when transpiling your admin code.
---
## Create the Admin UI Route
In this section, you’ll learn the basics of creating an admin UI route.
### Step 1: Create File
Custom admin UI routes are added under the `src/admin/routes` directory of your Medusa project. The path of the file depends on the path you want the route to be available under. It is based on [Next.js 13’s App Router](https://nextjs.org/docs/app/building-your-application/routing/defining-routes).
For example, if you want the route to be available in the admin dashboard under the path `/a/custom` you should create your admin route under the path `src/admin/routes/custom/page.tsx`.
:::tip
All admin routes are prefixed with `/a` by default.
:::
You can also create [dynamic routes](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes). For example, you can create the route `/a/custom/[id]` by creating an admin router under the path `src/admin/routes/custom/[id]/page.tsx`.
### Step 2: Create React Component in File
For an admin route to be valid, it must default export a React component. There are no restrictions on the content of the React component.
For example, you can create the file `src/admin/routes/custom/page.tsx` with the following content:
```tsx title=src/admin/routes/custom/page.tsx
const CustomPage = () => {
return (
<div>
This is my custom route
</div>
)
}
export default CustomPage
```
### Step 3: Test it Out
To test your admin UI route, run the following command in the root directory of the Medusa backend project:
```bash npm2yarn
npx @medusajs/medusa-cli develop
```
This will build your admin and opens a window in your default browser to `localhost:7001`. After you log in, if you go to `localhost:7001/a/custom`, you’ll find the page you just created.
:::note
When using the `develop` command, the admin dashboard will run in development mode and will restart whenever you make changes to your admin customizations. This allows you to see changes in the dashboard instantly during your development.
:::
---
## Show Route in Sidebar
You can add your routes into the admin dashboard sidebar by exporting an object of type `RouteConfig` import from `@medusajs/admin` in the same route file.
The object has one property `link`, which is an object having the following properties:
- `label`: a string indicating the sidebar item’s label of your custom route.
- `icon`: an optional React component that acts as an icon in the sidebar. If none provided, a default icon is used.
For example, you can change the content of the previous route you created to export a config object:
```tsx title=src/admin/routes/custom/page.tsx
import { RouteConfig } from "@medusajs/admin"
import { CustomIcon } from "../../icons/custom"
const CustomPage = () => {
return (
<div>
This is my custom route
</div>
)
}
export const config: RouteConfig = {
link: {
label: "Custom Route",
icon: CustomIcon,
},
}
export default CustomPage
```
---
## Retrieve Path Parameters
As mentioned earlier, you can create dynamic routes like `/a/custom/[id]` by creating a route file at the path `src/admin/routes/custom/[id]/page.tsx`.
To retrieve the path parameter, you can use the [useParams hook](https://reactrouter.com/en/main/hooks/use-params) retrieved from the [react-router-dom](https://reactrouter.com/en/main) package.
:::note
`react-router-dom` is available as one of the `@medusajs/admin` dependencies. You can also install it within your project using the following command:
```bash npm2yarn
npm install react-router-dom
```
If you're installing it in a plugin with admin customizations, make sure to include it in `peerDependencies`.
:::
For example:
```tsx title=src/admin/routes/custom/[id]/page.tsx
import { useParams } from "react-router-dom"
const CustomPage = () => {
const { id } = useParams()
return (
<div>
Passed ID: {id}
</div>
)
}
export default CustomPage
```
### Routing Functionalities
If you want to use routing functionalities such as linking to another page or navigating between pages, you can use `react-router-dom`'s utility hooks and functions.
For example, to add a link to another page:
```tsx title=src/admin/routes/custom/page.tsx
import { Link } from "react-router-dom"
const CustomPage = () => {
return (
<div>
<Link to={"/a/products"}>
View Products
</Link>
</div>
)
}
export default CustomPage
```
View [react-router-dom’s documentation](https://reactrouter.com/en/main) for other available components and hooks.
---
## Styling Route
Admin UI routes support [Tailwind CSS](https://tailwindcss.com/) by default.
For example, to customize your custom route:
<!-- eslint-disable max-len -->
```tsx title=src/admin/routes/custom/page.tsx
const CustomPage = () => {
return (
<div
className="bg-white p-8 border border-gray-200 rounded-lg">
This is my custom route
</div>
)
}
export default CustomPage
```
---
## Querying and Mutating Data
You might need to interact with the Medusa backend from your admin route. To do so, you can utilize the [Medusa React package](../medusa-react/overview.md). It contains a collection of queries and mutation built on `@tanstack/react-query` that lets you interact with the Medusa backend.
:::note
Make sure to also install the Medusa React package first if you’re intending to use it, as explained in the [Medusa React guide](../medusa-react/overview.md).
:::
For example, you can retrieve available products and display them in your route:
```tsx title=src/admin/routes/custom/page.tsx
import { useAdminProducts } from "medusa-react"
const CustomPage = () => {
const { products } = useAdminProducts()
return (
<div className="bg-white">
{products?.map((product) => product.title)}
</div>
)
}
export default CustomPage
```
You can also use `medusa-react` to interact with custom endpoints using the [createCustomAdminHooks utility function](../medusa-react/overview.md#custom-hooks).
---
## See Also
- [Admin widgets](./widgets.md)
- [Create a plugin for your admin customizations](../development/plugins/create.mdx)

1283
docs/content/admin/widgets.md Normal file
View File

File diff suppressed because it is too large Load Diff