Skip to content

Commit 76343de

Browse files
shahednassershahednasser
authored
chore(docs): cloud doc changes (automated) (#15036)
* chore(docs): automated cloud documentation update * fixes * add section on setting environment variable * Update instructions for backend URL in storefront Clarify the manual update process for backend URL in storefront configuration after DNS changes. * Clarify environment variable syntax in documentation Updated environment variable assignments for clarity. --------- Co-authored-by: shahednasser <[email protected]>
1 parent 128259a commit 76343de

File tree

10 files changed

+268
-41
lines changed

10 files changed

+268
-41
lines changed

‎.claude/skills/writing-docs/SKILL.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,11 @@ export const metadata = {
7878
- [ ] Documenting any option, method, or parameter tagged with `@ignore` in its TSDoc — skip these entirely
7979
- [ ] Touching `references/` or `specs/components/` directories
8080
- [ ] Using `we`, `us`, `let's`, `our` in prose (use "you" or imperative)
81-
- [ ] Using passive voice ("is created", "was updated") — write active
81+
- [ ] Using "Medusa API" to mean the backend — use "Medusa backend" instead
82+
- [ ] Writing "Medusa Cloud" — use "Medusa" (noun form) or "Cloud" (location/service)
83+
- [ ] Using `e.g.,` — write `for example` instead
84+
- [ ] Using em dashes (`—`) — rewrite sentence to avoid them
85+
- [ ] Using passive voice ("is created", "can be configured") — write active ("you can configure", "call X to create")
8286
- [ ] Writing code lines longer than 64 characters
8387
- [ ] Forgetting to add a new page to the sidebar file
8488
- [ ] Removing `${pageNumber}` from book page titles

‎.claude/skills/writing-docs/reference/cloud-style.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Cloud Style Guide
22

3-
The `cloud` project (`www/apps/cloud/`) covers how developers and technical users manage their Medusa applications on Medusa Cloud — creating projects, managing environments and deployments, configuring resources, and monitoring usage.
3+
The `cloud` project (`www/apps/cloud/`) covers how developers and technical users manage their Medusa applications on Cloud: creating projects, managing environments and deployments, configuring resources, and monitoring usage.
44

55
## Constraints
66

@@ -53,6 +53,7 @@ In this guide, you'll learn about <topic>.
5353

5454
## Writing Style
5555

56+
- **Cloud naming**: Never write "Medusa Cloud". Use **"Medusa"** when referring to it as a noun/subject ("Medusa allows you to..."), and **"Cloud"** when referring to it as a location or service ("Deploy to Cloud", "the Cloud dashboard")
5657
- **Second person**: "You create a project..." not "We create..." or "One can create..."
5758
- **Task-based H2 titles**: "Create a Project", "Manage Environment Variables", "Delete an Environment"
5859
- **Imperative numbered steps**: "Click **Save**", "Enter the environment name", "Select a region"
@@ -216,7 +217,7 @@ export const metadata = {
216217

217218
# {metadata.title}
218219

219-
In this guide, you'll learn how to configure a custom domain for your Medusa Cloud project.
220+
In this guide, you'll learn how to configure a custom domain for your Cloud project.
220221

221222
## What is a Custom Domain?
222223

‎.claude/skills/writing-docs/reference/vale-rules.md‎

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,16 +22,73 @@ Exceptions: `US` (United States) is allowed.
2222

2323
## Passive Voice
2424

25-
Vale warns on passive voice. Rewrite as active:
25+
Vale warns on passive voice. Rewrite as active. Pay special attention to "can be + past participle" constructions — rewrite as "you can + verb":
2626

2727
```
2828
❌ The workflow is created by calling createWorkflow.
2929
❌ Products are fetched from the database.
3030
❌ The configuration has been updated.
31+
❌ Custom domains can be configured in the settings.
3132
3233
✅ Call createWorkflow to create a workflow.
3334
✅ The service fetches products from the database.
3435
✅ Update the configuration.
36+
✅ You can configure custom domains in the settings.
37+
```
38+
39+
## Backend vs API Terminology
40+
41+
**Rule:** Use "backend" when referring to the Medusa server/application. Never use "API" as a synonym for the Medusa backend.
42+
43+
```
44+
❌ Serve your Medusa API.
45+
❌ Connect the storefront to the Medusa API.
46+
❌ The Medusa API handles the requests.
47+
48+
✅ Serve your Medusa backend.
49+
✅ Connect the storefront to the Medusa backend.
50+
✅ The Medusa backend handles the requests.
51+
```
52+
53+
Note: "API" is still correct when referring to specific API routes or endpoints (for example, "call the Products API", "the Admin API").
54+
55+
## Medusa Cloud Naming
56+
57+
**Rule:** Never write "Medusa Cloud" — use the shortened form depending on context.
58+
59+
- When referring to the product/platform as a noun, use **"Medusa"**
60+
- When referring to the platform as a location or service (e.g., deploying to it), use **"Cloud"**
61+
62+
```
63+
❌ Medusa Cloud allows you to deploy your application.
64+
✅ Medusa allows you to deploy your application.
65+
66+
❌ Deploy your project to Medusa Cloud.
67+
✅ Deploy your project to Cloud.
68+
69+
❌ The Medusa Cloud dashboard shows your deployments.
70+
✅ The Cloud dashboard shows your deployments.
71+
```
72+
73+
## Latin Abbreviations
74+
75+
**Rule:** Never use `e.g.,` — write `for example` instead.
76+
77+
```
78+
❌ Use a workflow step, e.g., to call an external API.
79+
✅ Use a workflow step, for example, to call an external API.
80+
```
81+
82+
## Em Dashes
83+
84+
**Rule:** Never use em dashes (`—`). Rewrite the sentence to avoid them.
85+
86+
```
87+
❌ The workflow runs the steps — in order — and compensates on failure.
88+
✅ The workflow runs the steps in order and compensates on failure.
89+
90+
❌ Use createStep — not direct service calls — for mutations.
91+
✅ Use createStep, not direct service calls, for mutations.
3592
```
3693

3794
## Problematic Words
@@ -103,8 +160,12 @@ Keep sentences concise. Vale suggests sentences under ~30 words. Split complex s
103160

104161
Before writing prose, check:
105162
- [ ] Any "we", "us", "let's", "our" → replace with "you" or imperative
106-
- [ ] Any passive voice constructions → rewrite active
163+
- [ ] Any passive voice constructions (including "can be configured", "is created", etc.) → rewrite active ("you can configure", "call X to create")
107164
- [ ] Any "simply", "just", "easy", etc. → remove
108165
- [ ] Code lines over 64 characters → break them
109166
- [ ] Bare URLs → wrap in `[label](url)`
110167
- [ ] `tsx` language tag for non-JSX TypeScript → change to `ts`
168+
- [ ] "Medusa API" used to mean the backend → replace with "Medusa backend"
169+
- [ ] "Medusa Cloud" anywhere → replace with "Medusa" (noun form) or "Cloud" (location/service)
170+
- [ ] `e.g.,` anywhere → replace with `for example`
171+
- [ ] Em dashes (`—`) anywhere → rewrite sentence to remove them

‎www/apps/cloud/app/deployments/access/page.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,4 +89,4 @@ You can find the storefront URL:
8989
2. In the project's dashboard, find the storefront URL in the environment's card under the "Storefront" title. You can copy the URL by clicking the copy icon next to it.
9090
3. Click the URL to open the storefront in a new browser tab.
9191

92-
You can also set up a custom domain for your storefront. Learn more in the [Storefront Custom Domain](../../storefront/page.mdx#storefront-custom-domain) guide.
92+
You can also set up a custom domain for your storefront. Learn more in the [Custom Domains](../../environments/custom-domains/page.mdx) guide.

‎www/apps/cloud/app/environments/custom-domains/page.mdx‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
import { Note, InlineIcon, CodeTab, CodeTabs } from "docs-ui"
2+
import { EllipsisHorizontal } from "@medusajs/icons"
3+
4+
export const metadata = {
5+
title: `Environment Custom Domains`,
6+
}
7+
8+
# {metadata.title}
9+
10+
In this guide, you'll learn how to set up custom domains for your backend and storefront deployed on Cloud.
11+
12+
## Custom Domains Overview
13+
14+
By default, Medusa environments are deployed with `medusajs.app` (backend) and `medusajs.site` (storefront) subdomains. You can configure custom domains to use your own branded URLs for both your backend and storefront.
15+
16+
You can configure custom domains per environment, allowing you to use different domains for Production, Staging, and preview environments based on your needs.
17+
18+
---
19+
20+
## Backend Custom Domains
21+
22+
Backend custom domains allow you to serve your Medusa backend from your own domain instead of the default `medusajs.app` subdomain.
23+
24+
<Note>
25+
26+
Backend custom domains are available for Scale and Enterprise plans only. Learn more about plan features on the [pricing page](../../pricing/page.mdx).
27+
28+
</Note>
29+
30+
### Prerequisites
31+
32+
To set up a backend custom domain, you need:
33+
34+
- A domain registered with a domain provider that supports CNAME records
35+
- Access to your domain's DNS settings
36+
37+
### Set Up Backend Custom Domain
38+
39+
To set up a backend custom domain:
40+
41+
1. Go to your project's dashboard in Cloud.
42+
2. Click on the environment card where you want to set up the backend custom domain.
43+
3. Click the **Settings** tab.
44+
4. Navigate to the **Domains** section.
45+
5. Under the **Custom Backend Domain** section, click the **Add Domain** button.
46+
6. In the modal that opens:
47+
- **Domain Step**: Enter your custom domain name (for example, `api.acme.com`)
48+
- **DNS Setup**: Follow the instructions to add the required DNS records with your domain provider
49+
7. Click **Done** to complete the setup.
50+
51+
You can track your domain's setup progress with the [Domain Status Indicators](#domain-status-indicators).
52+
53+
### Update Backend Domain in Storefront
54+
55+
To avoid downtime in you storefront while DNS changes propagate for your backend's custom domain, Medusa doesn't update the backend URL set in the storefront automatically. The storefront will still point to the backend's original subdomain.
56+
57+
Once you've verified that DNS changes have propagated and the custom domain is correctly pointing to the Medusa backend, you need to manually update the backend URL in your storefront's configuration to point to the new custom domain.
58+
59+
Based on your storefront framework, update the backend environment variable:
60+
61+
<CodeTabs group="storefront-framework">
62+
<CodeTab label="Next.js" value="nextjs">
63+
64+
```shell
65+
NEXT_PUBLIC_MEDUSA_BACKEND_URL= # Your Medusa backend's URL
66+
# Update any other envionment variable that uses the Medusa backend URL
67+
# For example:
68+
MEDUSA_BACKEND_URL= # Your Medusa backend's URL
69+
```
70+
71+
</CodeTab>
72+
<CodeTab label="SvelteKit / Tanstack Start" value="sveltekit-tanstack">
73+
74+
```shell
75+
VITE_MEDUSA_BACKEND_URL= # Your Medusa backend's URL
76+
# Update any other envionment variable that uses the Medusa backend URL
77+
# For example:
78+
MEDUSA_BACKEND_URL= # Your Medusa backend's URL
79+
```
80+
81+
</CodeTab>
82+
</CodeTabs>
83+
84+
To learn how to update environment variables on Cloud, see the [Environment Variables](../environment-variables/page.mdx) guide.
85+
86+
After updating the backend URL, [redeploy your environment](../../deployments/page.mdx#redeploy-a-deployment). Your live storefront will now connect to your Medusa backend through the new custom domain without any downtime.
87+
88+
---
89+
90+
## Storefront Custom Domains
91+
92+
Storefront custom domains allow you to serve your storefront from your own domain instead of the default `medusajs.site` subdomain.
93+
94+
<Note>
95+
96+
Storefront custom domains are available for Launch, Scale, and Enterprise plans only. Learn more about plan features on the [pricing page](../../pricing/page.mdx).
97+
98+
</Note>
99+
100+
### Prerequisites
101+
102+
To set up a storefront custom domain, you need:
103+
104+
- A domain registered with a domain provider that supports either ALIAS records or top-level CNAME records
105+
- Access to your domain's DNS settings
106+
107+
### Set Up Storefront Custom Domain
108+
109+
#### From Project Overview
110+
111+
If no custom domain is configured for your storefront environment, you'll see a **Setup Custom Domain** link in the environment card:
112+
113+
1. Go to your project's dashboard in Cloud.
114+
2. In the environment card (for example, Production), click the **Setup Custom Domain** link next to the health status.
115+
116+
#### From Environment Settings
117+
118+
1. Go to your project's dashboard in Cloud.
119+
2. Click on the environment card where you want to set up the custom domain.
120+
3. Click the **Settings** tab.
121+
4. Navigate to the **Domains** section.
122+
5. Click the **Add Domain** button.
123+
6. In the modal that opens:
124+
- **Domain Step**: Enter your custom domain name (for example, `shop.acme.com`)
125+
- **DNS Setup**: Follow the instructions to add the required DNS records with your domain provider
126+
7. Click **Done** to complete the setup.
127+
128+
You can track your domain's setup progress with the [Domain Status Indicators](#domain-status-indicators).
129+
130+
---
131+
132+
## Domain Status Indicators
133+
134+
After adding a custom domain, you'll see a status below the domain name that help you track the setup progress:
135+
136+
- **Pending** (gray clock icon): Domain has been added but DNS verification is pending
137+
- **Configured** (blue clock icon): DNS records are detected but verification is in progress
138+
- **Verified** (green checkmark icon): Domain is fully configured and active
139+
140+
Domain activation typically completes within a few minutes to 48 hours, depending on DNS propagation times.
141+
142+
---
143+
144+
## Manage Custom Domains
145+
146+
### Remove Custom Domain
147+
148+
<Note type="warning">
149+
150+
Removing a custom domain will immediately stop serving traffic from that domain. Make sure to update any integrations or client applications before removing a domain.
151+
152+
</Note>
153+
154+
To remove a custom domain:
155+
156+
1. In the **Domains** section of your environment settings, find the domain you want to remove.
157+
2. Click the <InlineIcon Icon={EllipsisHorizontal} alt="Options" /> button next to the domain and select **Remove** from the dropdown.
158+
3. In the confirmation dialog, type the domain name exactly as shown to confirm the removal.
159+
4. Click **Remove Domain** to complete the action.
160+
161+
---
162+
163+
## Troubleshooting
164+
165+
### Domain Verification
166+
167+
If your domain remains in **Pending** or **Configured** status:
168+
169+
1. **Check DNS records**: Verify that you've added all required DNS records exactly as provided in the DNS setup instructions.
170+
2. **Wait for propagation**: DNS changes can take up to 48 hours to propagate globally.
171+
3. **Contact support**: If your domain hasn't verified after 48 hours, contact support for assistance.
172+
173+
### Storefront Not Connecting to Backend After Custom Domain Setup
174+
175+
If your storefront isn't connecting to the backend after setting up a backend custom domain, make sure you [updated the backend URL in your storefront's environment variables](#update-backend-domain-in-storefront) and redeployed your environment.

‎www/apps/cloud/app/projects/page.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ When you choose a subdomain for your project, it must be at least five character
142142
- `development`
143143
- `proxy`
144144

145-
If you also deployed a storefront with your Medusa application, its URL will be a subdomain of `medusajs.site`. For example, if your backend's subdomain is `my-store`, your storefront's URL will be `my-store.medusajs.site`. You can also add a custom domain, as explained in the [Storefront Custom Domain](../storefront/page.mdx#storefront-custom-domain) guide.
145+
If you also deployed a storefront with your Medusa application, its URL will be a subdomain of `medusajs.site`. For example, if your backend's subdomain is `my-store`, your storefront's URL will be `my-store.medusajs.site`. You can also add a custom domain, as explained in the [Custom Domains](../environments/custom-domains/page.mdx) guide.
146146

147147
---
148148

@@ -243,7 +243,7 @@ Then, to add a storefront to an existing project:
243243

244244
Cloud will then deploy the storefront along with the Medusa application. Once the deployment is complete, you'll be able to access the storefront from the Production environment card in the project's dashboard.
245245

246-
You can also set a custom domain for the storefront, as explained in the [Storefront](../storefront/page.mdx#storefront-custom-domain) guide.
246+
You can also set a custom domain for the storefront, as explained in the [Custom Domains](../environments/custom-domains/page.mdx) guide.
247247

248248
---
249249

‎www/apps/cloud/app/storefront/page.mdx‎

Lines changed: 1 addition & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -71,35 +71,7 @@ If you're using a different framework for your storefront, contact support to re
7171

7272
By default, storefronts are deployed at the `medusajs.site` subdomain. The domain prefix is the same as the Medusa application's subdomain. For example, if your Medusa application is at `my-store.medusajs.app`, your storefront will be at `my-store.medusajs.site`.
7373

74-
You can also set up a custom domain for your storefront to use a branded URL.
75-
76-
### Prerequisites
77-
78-
To set up a custom domain for your storefront, you need a domain registered with a domain provider that supports either ALIAS records or top-level CNAME records.
79-
80-
<Note>
81-
82-
Custom storefront domains are available for Launch, Scale, and Enterprise plans only. Learn more about plan features on the [pricing page](../pricing/page.mdx).
83-
84-
</Note>
85-
86-
### Set Up Storefront Custom Domain
87-
88-
You can set up storefront custom domains per environment. For example, you can set up a custom domain for the Production environment while keeping the default domain for the Staging and preview environments.
89-
90-
To set up a storefront custom domain for an environment:
91-
92-
1. Go to a [project's dashboard](../projects/page.mdx#open-project-dashboard) in Cloud.
93-
2. Click on the environment's card where you want to set up the custom domain. For example, the Production environment.
94-
3. In the environment's dashboard, click on the "Settings" tab.
95-
4. Choose the "Storefront Domains" tab from the sidebar.
96-
5. Click on the "Add domain" button.
97-
6. A form with two steps will open:
98-
- **Domain Step**: Enter your custom domain name. For example, `acme.com`.
99-
- **DNS Step**: Follow the instructions to add the necessary DNS records with your domain provider.
100-
7. Once you're done, click the "Done" button.
101-
102-
Your custom domain will be active once the DNS changes propagate, which may take up to 48 hours.
74+
You can also set up a custom domain for your storefront to use a branded URL. For detailed instructions on setting up and managing custom domains for your storefront, refer to the [Custom Domains](../environments/custom-domains/page.mdx#storefront-custom-domains) guide.
10375

10476
---
10577

‎www/apps/cloud/generated/edit-dates.mjs‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
export const generatedEditDates = {
22
"app/page.mdx": "2026-01-08T09:12:42.756Z",
33
"app/organization/page.mdx": "2025-06-12T14:43:20.772Z",
4-
"app/projects/page.mdx": "2026-01-08T08:58:12.499Z",
4+
"app/projects/page.mdx": "2026-04-08T16:20:15.030Z",
55
"app/environments/page.mdx": "2026-01-07T12:07:20.976Z",
66
"app/deployments/page.mdx": "2026-01-07T13:12:29.617Z",
77
"app/organizations/page.mdx": "2026-03-27T09:49:54.966Z",
@@ -29,8 +29,9 @@ export const generatedEditDates = {
2929
"app/emails/page.mdx": "2026-03-27T09:46:46.277Z",
3030
"app/emails/react-email/page.mdx": "2026-03-27T09:46:46.277Z",
3131
"app/user/page.mdx": "2025-12-17T12:03:18.968Z",
32-
"app/deployments/access/page.mdx": "2026-01-08T08:52:48.924Z",
32+
"app/deployments/access/page.mdx": "2026-04-08T16:20:22.886Z",
3333
"app/projects/prerequisites/page.mdx": "2026-02-09T14:40:20.415Z",
34-
"app/storefront/page.mdx": "2026-03-27T09:46:46.272Z",
35-
"app/projects/rename-repo-branch/page.mdx": "2026-03-18T09:23:58.584Z"
34+
"app/storefront/page.mdx": "2026-04-08T16:19:50.391Z",
35+
"app/projects/rename-repo-branch/page.mdx": "2026-03-18T09:23:58.584Z",
36+
"app/environments/custom-domains/page.mdx": "2026-04-08T16:19:33.834Z"
3637
}

0 commit comments

Comments
 (0)
⚡