docs: add a need help button (#8069)

* docs: add a need help button

* change github issue link

* responsive fixes
This commit is contained in:
Shahed Nasser
2024-07-11 10:29:13 +03:00
committed by GitHub
parent f460348280
commit a8df528c65
23 changed files with 219 additions and 107 deletions

View File

@@ -3,6 +3,7 @@
import {
AnalyticsProvider,
ColorModeProvider,
helpButtonNotification,
HooksLoader,
LearningPathProvider,
MobileProvider,
@@ -28,7 +29,7 @@ const Providers = ({ children }: ProvidersProps) => {
<ColorModeProvider>
<ModalProvider>
<LearningPathProvider>
<NotificationProvider>
<NotificationProvider initial={[helpButtonNotification]}>
<ScrollControllerProvider scrollableSelector="#main">
<SidebarProvider>
<PaginationProvider>

View File

@@ -1,9 +0,0 @@
import AclErrorSection from "../_sections/other/s3-acl.mdx"
export const metadata = {
title: `S3 Plugin ACL Error`,
}
# {metadata.title}
<AclErrorSection />

View File

@@ -1,12 +1,12 @@
If you're running the Medusa backend through tools like VSCode or GitHub Codespaces, you must ensure that:
If you're running the Medusa application 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:
- [VSCode local development.](https://code.visualstudio.com/docs/editor/port-forwarding)
- [VSCode remote development.](https://code.visualstudio.com/docs/remote/ssh#_forwarding-a-port-creating-ssh-tunnel)
- [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 [adminCors](/references/medusa-config#adminCors) Medusa configuration. Your tool will show you what the forwarded address is.
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 `adminCors` 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:
After setting these configurations, run your Medusa application 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

View File

@@ -1,8 +1,8 @@
This error typically occurs when you set up a Medusa project with `create-medusa-app` and try to run the Medusa backend.
This error typically occurs when you set up a Medusa project with `create-medusa-app` and try to run the Medusa application.
To resolve this issue, make sure you change into the `backend` directory of the Medusa project you created before trying to start the Medusa backend:
To resolve this issue, make sure you change into the application's directory of the Medusa project you created before trying to start the Medusa application:
```bash npm2yarn
cd backend
npx medusa develop
cd my-medusa-store
npm run dev
```

View File

@@ -1,10 +1,10 @@
When you start your Medusa backend you may run into the following error:
When you start your Medusa application you may run into the following error:
```bash
Error: connect ECONNREFUSED ::1:5432
```
This error occurs because the backend couldn't connect to the PostgreSQL database. The issue could be one of the following:
This error occurs because the application couldn't connect to the PostgreSQL database. The issue could be one of the following:
1. PostgreSQL server isn't running. Make sure it's always running while the Medusa backend is running.
2. The connection URL to your PostgreSQL database is incorrect. This could be because of incorrect credentials, port number, or connection URL format. The format should be `postgres://[user][:password]@[host][:port]/[dbname]`. Make sure that the connection URL format is correct, and the credentials passed in the URL are correct. You can learn more about formatting the connection URL [here](/references/medusa-config#postgresql-configurations)
1. PostgreSQL server isn't running. Make sure it's always running while the Medusa application is running.
2. The connection URL to your PostgreSQL database is incorrect. This could be because of incorrect credentials, port number, or connection URL format. The format should be `postgres://[user][:password]@[host][:port]/[dbname]`. Make sure that the connection URL format is correct, and the credentials passed in the URL are correct. You can learn more about formatting the connection URL [here](/references/medusa-config#databaseUrl)

View File

@@ -1,4 +1,4 @@
When connecting your Medusa backend to a PostgreSQL Docker container, make sure the `5432` port is exposed.
When connecting your Medusa application to a PostgreSQL Docker container, make sure the `5432` port is exposed.
To do that, either pass the `-p` option to the `docker run` command. For example:
@@ -22,4 +22,4 @@ npx create-medusa-app@latest --db-url "postgres://user:password@localhost:<YOUR_
Where `<YOUR_PORT>` is the exposed port if it's different than `5432`.
Refer to the [databaseUrl configuration documentation](/references/medusa-config#databaseUrl) to learn how to set the database URL for an installed Medusa backend.
Refer to the [databaseUrl configuration documentation](/references/medusa-config#databaseUrl) to learn how to set the database URL for an installed Medusa application.

View File

@@ -1,4 +1,4 @@
If you are experiencing connection issues when trying to access your Medusa backend from a storefront or the admin dashboard, it is most likely due to Cross-Origin Resource Sharing (CORS) issues.
If you are experiencing connection issues when trying to access your Medusa application from a storefront or the admin dashboard, it is most likely due to Cross-Origin Resource Sharing (CORS) issues.
You might see a log in your browser console, that looks like this:
@@ -12,8 +12,11 @@ module.exports = defineConfig({
http: {
storeCors: process.env.STORE_CORS,
adminCors: process.env.ADMIN_CORS,
authCors: process.env.AUTH_CORS,
},
// ...
},
})
```
Learn more about these configurations in [this documentation](/references/medusa-config#http)

View File

@@ -1,4 +1,4 @@
When you run your backend you may run to an error similar to the following:
When you run your Medusa application you may run to an error similar to the following:
```bash
code: 'EADDRINUSE',
@@ -10,5 +10,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.mdx#build-command-options) or [storefront](../starters/nextjs-medusa-starter.mdx#changing-medusa-backend-url).
- Change the default port used by the Medusa application. 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 application, such as in your [admin](/references/medusa-config#admin) or [storefront](../../../nextjs-starter/page.mdx#change-medusa-application-url).
- Terminate other processes running on port `9000`.

View File

@@ -1,14 +0,0 @@
If you're using the S3 Plugin and, when you upload an image, you receive the following error on your Medusa backend:
```bash noReport
AccessControlListNotSupported: The bucket does not allow ACLs
```
Try the following:
1. Go to your S3 Bucket, then choose the Permissions tab.
2. Scroll to Object Ownership and click the Edit button.
3. Select ACLs enabled and choose for Object Ownership the radio button Bucket owner preferred.
4. Click the Save Changes.
Try uploading again after making this change. Upload should be successful.

View File

@@ -1,22 +0,0 @@
export const metadata = {
title: `Database Transaction Not Rolling Back When Promise.all is Used`,
}
# {metadata.title}
Due to how `Promise.all` works, when you run multiple database transactions within it, these transactions may not be rolled back when an error occurs.
To mitigate this issue, use the `promiseAll` function which can be imported from `@medusajs/utils`. For example:
```ts
import { promiseAll } from "@medusajs/utils"
import { TransactionBaseService } from "@medusajs/medusa"
class MyService extends TransactionBaseService {
async performTransactions() {
return await promiseAll([
// your transactions....
])
}
}
```

View File

@@ -1,12 +1,13 @@
import TypeError from "../_sections/create-medusa-app-errors/typeerror.mdx"
import OtherErrors from "../_sections/create-medusa-app-errors/other-errors.mdx"
import NextjsError from "../_sections/nextjs/cma-option.mdx"
import InvalidTokenError from "../_sections/create-medusa-app-errors/no-browser-token-error.mdx"
import DockerSection from "../_sections/database-errors/docker.mdx"
import DbUrlError from "../_sections/create-medusa-app-errors/db-url-error.mdx"
import ForwardingError from "../_sections/create-medusa-app-errors/forwarding.mdx"
export const metadata = {
title: `Common Create-React-App Errors`,
title: `Common create-medusa-app Errors`,
}
# {metadata.title}
@@ -41,6 +42,12 @@ export const metadata = {
---
## Can't Access Next.js Starter Storefront
<NextjsError />
---
## Other Errors
<OtherErrors />

View File

@@ -4,14 +4,12 @@ export const metadata = {
# {metadata.title}
{/* TODO add link [Upgrade Guides](../upgrade-guides/page.mdx) */}
If you run into errors after updating Medusa and its dependencies, it's highly recommended to check the Upgrade Guides if there is a specific guide for your version. These guides include steps required to perform after upgrading Medusa.
If there's no upgrade guide for your version, make sure that you ran the `migrations` command in the root directory of your Medusa backend:
If there's no upgrade guide for your version, make sure that you ran the `migrations` command in the root directory of your Medusa application:
```bash
npx medusa migrations run
```
This ensures your backend has the latest database structure required. Then, try running your Medusa backend again and check whether the same error occurs.
This ensures your application has the latest database structure required. Then, try running your Medusa application again and check whether the same error occurs.

View File

@@ -6,10 +6,4 @@ export const metadata = {
# {metadata.title}
<Note type="soon">
The following troubleshooting guides were created for Medusa v1 and might not be useful for Medusa v2.
</Note>
<ChildDocs />

View File

@@ -923,14 +923,6 @@ export const filesMap = [
"filePath": "/www/apps/resources/app/storefront-development/tips/page.mdx",
"pathname": "/storefront-development/tips"
},
{
"filePath": "/www/apps/resources/app/troubleshooting/_s3-plugin-acl-error/page.mdx",
"pathname": "/troubleshooting/_s3-plugin-acl-error"
},
{
"filePath": "/www/apps/resources/app/troubleshooting/_transaction-promise-all/page.mdx",
"pathname": "/troubleshooting/_transaction-promise-all"
},
{
"filePath": "/www/apps/resources/app/troubleshooting/cors-errors/page.mdx",
"pathname": "/troubleshooting/cors-errors"

View File

@@ -7705,17 +7705,10 @@ export const generatedSidebar = [
{
"loaded": true,
"isPathHref": true,
"title": "Configurations",
"path": "/references/medusa-config",
"title": "Medusa Configurations",
"hasTitleStyling": true,
"children": [
{
"loaded": true,
"isPathHref": true,
"path": "/references/medusa-config",
"title": "Medusa Application",
"children": []
}
]
"children": []
},
{
"loaded": true,
@@ -7865,7 +7858,7 @@ export const generatedSidebar = [
{
"loaded": true,
"isPathHref": true,
"title": "Medusa Backend",
"title": "Medusa Application",
"hasTitleStyling": true,
"children": [
{

View File

@@ -3,6 +3,7 @@
import {
AnalyticsProvider,
ColorModeProvider,
helpButtonNotification,
HooksLoader,
LearningPathProvider,
MobileProvider,
@@ -30,7 +31,7 @@ const Providers = ({ children }: ProvidersProps) => {
<LearningPathProvider
baseUrl={process.env.NEXT_PUBLIC_BASE_PATH || "/resources"}
>
<NotificationProvider>
<NotificationProvider initial={[helpButtonNotification]}>
<ScrollControllerProvider scrollableSelector="#main">
<SidebarProvider>
<PaginationProvider>

View File

@@ -1965,14 +1965,9 @@ export const sidebar = sidebarAttachHrefCommonOptions([
],
},
{
title: "Configurations",
path: "/references/medusa-config",
title: "Medusa Configurations",
hasTitleStyling: true,
children: [
{
path: "/references/medusa-config",
title: "Medusa Application",
},
],
},
{
title: "General",
@@ -2067,7 +2062,7 @@ export const sidebar = sidebarAttachHrefCommonOptions([
],
},
{
title: "Medusa Backend",
title: "Medusa Application",
hasTitleStyling: true,
children: [
{

View File

@@ -0,0 +1,52 @@
"use client"
import { Bug, Discord, Github } from "@medusajs/icons"
import clsx from "clsx"
import Link from "next/link"
import React from "react"
export const HelpButtonActions = () => {
const actions = [
{
title: "Troubleshooting Guides",
url: "https://docs.medusajs.com/v2/resources/troubleshooting",
icon: <Bug />,
},
{
title: "Create a GitHub Issue",
url: "https://github.com/medusajs/medusa/issues/new/choose",
icon: <Github />,
},
{
title: "Get Support on Discord",
url: "https://discord.gg/medusajs",
icon: <Discord />,
},
]
return (
<div
className={clsx(
"bg-medusa-bg-component shadow-elevation-flyout",
"flex flex-col rounded-docs_DEFAULT",
"mr-0 ml-auto"
)}
>
{actions.map((action, index) => (
<Link
href={action.url}
className={clsx(
"px-docs_0.5 py-docs_0.25 text-medusa-fg-base",
"flex flex-row items-center gap-docs_0.5",
"hover:bg-medusa-bg-component-hover",
index !== 0 && "border-t border-medusa-border-base border-solid"
)}
key={index}
target="_blank"
>
{action.icon}
<span>{action.title}</span>
</Link>
))}
</div>
)
}

View File

@@ -0,0 +1,102 @@
"use client"
import React, { useCallback, useEffect, useRef, useState } from "react"
import { Button } from "@/components"
import clsx from "clsx"
import { CSSTransition } from "react-transition-group"
import { HelpButtonActions } from "./Actions"
import { useIsBrowser } from "../.."
export const HelpButton = () => {
const [showText, setShowText] = useState(false)
const [showHelp, setShowHelp] = useState(false)
const ref = useRef<HTMLDivElement>(null)
const isBrowser = useIsBrowser()
const onClickOutside = useCallback(
(e: MouseEvent) => {
if (!ref.current?.contains(e.target as Node)) {
setShowHelp(false)
setShowText(false)
}
},
[ref.current]
)
useEffect(() => {
if (!isBrowser) {
return
}
window.document.addEventListener("click", onClickOutside)
return () => {
window.document.removeEventListener("click", onClickOutside)
}
}, [isBrowser])
useEffect(() => {
if (showHelp) {
setShowText(true)
}
}, [showHelp])
return (
<div
className={clsx(
"mr-0 ml-auto w-fit",
"flex flex-col gap-docs_0.5",
"max-[767px]:fixed max-[767px]:bottom-docs_1 max-[767px]:right-docs_1"
)}
ref={ref}
>
{showHelp && <HelpButtonActions />}
<Button
variant="secondary"
className={clsx(
"!p-[10px] !shadow-elevation-flyout dark:!shadow-elevation-flyout-dark !text-medusa-fg-subtle",
"rounded-full border-0 !flex relative mr-0 ml-auto",
"h-docs_3 min-w-docs_3 !txt-medium-plus lg:txt-large-plus transition-[width] duration-300",
!showText && "!gap-0"
)}
onMouseOver={() => setShowText(true)}
onMouseLeave={() => {
if (!showHelp) {
setShowText(false)
}
}}
onClick={() => {
setShowHelp((prev) => !prev)
}}
>
<CSSTransition
in={showText}
timeout={300}
onEnter={(node: HTMLElement) => {
node.style.width = `0px`
}}
onEntering={(node: HTMLElement) => {
node.style.width = `${node.scrollWidth}px`
setTimeout(() => {
node.style.opacity = `1`
}, 100)
}}
onExiting={(node: HTMLElement) => {
node.style.width = `0px`
node.style.opacity = `0`
}}
>
<span
className={clsx("opacity-0 w-0 text-nowrap")}
style={{
transition: `width cubic-bezier(0.4, 0, 0.2, 1) 300ms, opacity cubic-bezier(0.4, 0, 0.2, 1) 150ms`,
}}
>
Need help
</span>
</CSSTransition>
<span>?</span>
</Button>
</div>
)
}

View File

@@ -29,7 +29,7 @@ export const NotificationContainer = () => {
"flex fixed flex-col gap-docs_0.5 right-0",
"md:w-auto w-full overflow-y-auto",
"max-h-[50%] md:max-h-[calc(100vh-57px)]",
notifications.length && "max-[768px]:h-[50%]",
"max-[768px]:max-h-[50%]",
className
)}
>

View File

@@ -22,6 +22,7 @@ export * from "./ExpandableNotice"
export * from "./FeatureFlagNotice"
export * from "./Feedback"
export * from "./Feedback/Solutions"
export * from "./HelpButton"
export * from "./HooksLoader"
export * from "./Icons"
export * from "./InlineIcon"

View File

@@ -1,7 +1,8 @@
import React from "react"
import { Badge, NavbarItem } from "@/components"
import { OptionType } from "./hooks"
import { Badge, NavbarItem, HelpButton } from "@/components"
import { OptionType } from "@/hooks"
import { SidebarItemType } from "types"
import { NotificationItemType } from "@/providers"
export const GITHUB_ISSUES_PREFIX = `https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml`
export const GITHUB_UI_ISSUES_PREFIX = `https://github.com/medusajs/ui/issues/new?labels=documentation`
@@ -259,3 +260,8 @@ export const searchFiltersV1: OptionType[] = [
label: "UI",
},
]
export const helpButtonNotification: NotificationItemType = {
layout: "empty",
children: <HelpButton />,
}

View File

@@ -1,6 +1,6 @@
"use client"
import React, { createContext, useContext, useReducer } from "react"
import React, { createContext, useContext, useMemo, useReducer } from "react"
import { NotificationItemProps, NotificationContainer } from "@/components"
import uuid from "react-uuid"
@@ -69,15 +69,27 @@ const NotificationContext = createContext<NotificationContextType | null>(null)
export type NotificationProviderProps = {
children?: React.ReactNode
initial?: NotificationItemType[]
}
export const NotificationProvider = ({
children,
initial = [],
}: NotificationProviderProps) => {
const [notifications, dispatch] = useReducer(notificationReducer, [])
const generateId = () => uuid()
const normalizedInitial = useMemo(() => {
return initial.map((notif) => ({
id: generateId(),
...notif,
}))
}, [initial])
const [notifications, dispatch] = useReducer(
notificationReducer,
normalizedInitial
)
const addNotification = (notification: NotificationItemType) => {
if (!notification.id) {
notification.id = generateId()