Skip to content

Commit 0167bd0

Browse files
atinuxatinux
committed
docs: simplify usage for studio setup
1 parent 82a325c commit 0167bd0

File tree

2 files changed

+133
-106
lines changed

2 files changed

+133
-106
lines changed

‎docs/content/docs/9.studio/2.setup.md‎

Lines changed: 120 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -13,114 +13,68 @@ This documentation covers only the new open-source Nuxt Studio module.
1313
Click here to view the documentation for the legacy standalone platform.
1414
::
1515

16-
## Install
16+
## Installation
1717

18-
Add the Nuxt Studio module to your project:
18+
Install Nuxt Studio using the Nuxt CLI within your project:
1919

20-
::code-group
21-
```bash [pnpm]
22-
pnpm add nuxt-studio@alpha
20+
```bash [Terminal]
21+
npx nuxt module add nuxt-studio@alpha
2322
```
2423

25-
```bash [npm]
26-
npm install nuxt-studio@alpha
27-
```
24+
::tip{icon="i-lucide-rocket"}
25+
Start your development server and start editing your Nuxt Content website.
26+
::
2827

29-
```bash [yarn]
30-
yarn add nuxt-studio@alpha
31-
```
28+
## Development mode
3229

33-
```bash [bun]
34-
bun add nuxt-studio@alpha
35-
```
36-
::
30+
When running locally, **any file changes will be synchronized in real time with your local filesystem**.
3731

38-
Alternatively, use the Nuxt CLI to automatically add the module:
32+
The publish system is only available in production mode. Use your current workflow (git command, IDE, GitHub Desktop...) to commit your changes.
3933

40-
```bash [Terminal]
41-
npx nuxi module add nuxt-studio@alpha
42-
```
34+
## Production mode
4335

44-
## Configure
36+
While Nuxt Studio can be useful during development (especially with the upcoming Studio editor) its main advantage is the ability to publish changes directly from your production website.
4537

46-
Add the module to your `nuxt.config.ts` and configure your repository based on your Git provider:
38+
In order to publish changes in production, you need to configure the git repository:
4739

4840
```ts [nuxt.config.ts]
4941
export default defineNuxtConfig({
50-
modules: [
51-
'@nuxt/content',
52-
'nuxt-studio'
53-
],
54-
5542
studio: {
56-
// Studio admin route (default: '/_studio')
57-
route: '/_studio',
58-
5943
// Git repository configuration (owner and repo are required)
6044
repository: {
6145
provider: 'github', // 'github' or 'gitlab'
6246
owner: 'your-username', // your GitHub/GitLab username or organization
6347
repo: 'your-repo', // your repository name
64-
branch: 'main', // the branch to commit to (default: main)
65-
}
66-
}
67-
})
68-
```
69-
70-
### Repository Options
71-
72-
#### Root directory `default: ''`
73-
74-
If your Nuxt Content application is in a monorepo or subdirectory, specify the `rootDir` option to point to the correct location.
75-
76-
```ts [nuxt.config.ts]
77-
export default defineNuxtConfig({
78-
studio: {
79-
repository: {
80-
...
81-
rootDir: 'docs'
82-
}
83-
}
84-
})
85-
```
86-
87-
#### Private Repository Access `default: true`
88-
89-
By default, Studio requests access to both public and private repositories.
90-
91-
Setting `private: false` limits the OAuth scope to public repositories only, which may be preferable for security or compliance reasons when working with public repositories.
92-
93-
```ts [nuxt.config.ts]
94-
export default defineNuxtConfig({
95-
studio: {
96-
repository: {
97-
...
98-
private: false
48+
branch: 'main', // the branch to commit to (default: 'main')
9949
}
10050
}
10151
})
10252
```
10353

104-
## Dev mode
54+
::callout{to="#options"}
55+
Read more about all the available options.
56+
::
10557

106-
🚀 That’s all you need to enable Studio in local.
58+
### OAuth Configuration
10759

108-
Once your project is running locally, any file changes will be synchronized in real time with the file system.
60+
To enable this Nuxt Studio supports authentication through both GitHub and GitLab OAuth providers allowing you to log in and publish updates from production.
10961

110-
::warning
111-
The publish system is only available in production mode. You can use your classical workflow (IDE, CLI, GitHub Desktop...) to publish your changes in local.
62+
::tip{icon="i-lucide-info" to="/docs/studio/providers#oauth-providers"}
63+
Follow the setup instructions for your Git provider.
11264
::
11365

114-
## Production mode
66+
Once your OAuth app is setup, you should have your environment variables set in your hosting provider.
11567

116-
While Nuxt Studio can be useful during development (especially with the upcoming Studio editor) its main advantage is the ability to publish changes directly from your production website.
117-
118-
### OAuth Configuration
119-
120-
To enable this Nuxt Studio supports authentication through both GitHub and GitLab OAuth providers allowing you to log in and publish updates from production.
68+
::code-group
69+
```bash [GitHub]
70+
STUDIO_GITHUB_CLIENT_ID=<your_github_client_id>
71+
STUDIO_GITHUB_CLIENT_SECRET=<your_github_client_secret>
72+
```
12173

122-
::tip{icon="i-lucide-info" to="/docs/studio/github#oauth-providers"}
123-
Choose your provider and follow the dedicated setup instructions for your Git provider in this section.
74+
```bash [GitLab]
75+
STUDIO_GITLAB_APPLICATION_ID=<your_gitlab_application_id>
76+
STUDIO_GITLAB_APPLICATION_SECRET=<your_gitlab_secret>
77+
```
12478
::
12579

12680
### Deployment
@@ -144,32 +98,95 @@ export default defineNuxtConfig({
14498
})
14599
```
146100

147-
### Accessing Studio
101+
### Open Studio
148102

149-
After deployment, access the Studio interface by navigating to your configured route (default: `/_studio`):
103+
Once deployed, open Studio by navigating to your configured route (default: `/_studio`):
150104

151105
1. Click the login button if it does not directly redirect to the OAuth app authorization page
152106
2. Authorize the OAuth application
153107
3. You'll be redirected back to Studio ready to edit your content
154108

155-
::note
156-
Secure OAuth-based login with **Google** should be available quickly in the Beta release.
109+
::tip
110+
You can also use the shortcut `CMD` + `.` to redirect to the Studio route.
157111
::
158112

159-
::tip
160-
You can also use the shortcut `CMD` + `K` to redirect to the Studio route.
113+
::note
114+
OAuth-based login with **Google** will be available soon.
161115
::
162116

163-
## Internationalization
117+
## Options
118+
119+
Add the module to your `nuxt.config.ts` and configure your repository based on your Git provider:
120+
121+
### Admin route
122+
123+
Customize the login route using the `route` option:
124+
125+
```ts [nuxt.config.ts]
126+
export default defineNuxtConfig({
127+
studio: {
128+
route: '/admin', // default: '/_studio'
129+
}
130+
})
131+
```
132+
133+
### Repository
134+
135+
Use the `repository` option to specify your git repository to sync in production mode.
136+
137+
```ts [nuxt.config.ts]
138+
export default defineNuxtConfig({
139+
studio: {
140+
repository: {
141+
provider: 'github', // 'github' or 'gitlab', default: 'github'
142+
owner: 'your-username', // your GitHub/GitLab username or organization
143+
repo: 'your-repo', // your repository name
144+
branch: 'main', // the branch to commit to (default: main)
145+
}
146+
}
147+
})
148+
```
149+
150+
#### Root directory `default: ''`
151+
152+
If your Nuxt Content application is in a monorepo or subdirectory, specify the `rootDir` option to point to the correct location.
153+
154+
```ts [nuxt.config.ts]
155+
export default defineNuxtConfig({
156+
studio: {
157+
repository: {
158+
...
159+
rootDir: 'docs'
160+
}
161+
}
162+
})
163+
```
164+
165+
#### Private Repository Access `default: true`
166+
167+
By default, Studio requests access to both public and private repositories.
168+
169+
Setting `private: false` limits the OAuth scope to public repositories only, which may be preferable for security or compliance reasons when working with public repositories.
170+
171+
```ts [nuxt.config.ts]
172+
export default defineNuxtConfig({
173+
studio: {
174+
repository: {
175+
...
176+
private: false
177+
}
178+
}
179+
})
180+
```
181+
182+
### Internationalization
164183

165184
Nuxt Studio includes built-in internationalization support with the following languages available:
166185

167186
- 🇬🇧 **English** (default)
168187
- 🇫🇷 **French**
169188

170-
### Configuration
171-
172-
Set your preferred language in your `nuxt.config.ts`:
189+
Set your preferred language using the `i18n` option:
173190

174191
```ts [nuxt.config.ts]
175192
export default defineNuxtConfig({
@@ -187,6 +204,20 @@ This will translate:
187204
- Monaco editor snippets and code completion
188205
- Contextual messages and notifications
189206

190-
### Contributions
207+
::callout{icon="i-lucide-heart-handshake"}
208+
Community contributions for new language translations are welcome! If you'd like to add support for a new language, please visit the [GitHub repository](https://github.com/nuxt-content/studio) and drop a pull request.
209+
::
210+
211+
### Dev mode
212+
213+
If you want to use test locally your production setup, disable the `dev` option:
214+
215+
```ts [nuxt.config.ts]
216+
export default defineNuxtConfig({
217+
studio: {
218+
dev: false
219+
}
220+
})
221+
```
191222

192-
Community contributions for new language translations are welcome! If you'd like to add support for a new language, please visit the [GitHub repository](https://github.com/nuxt-content/studio) and drop a pull request 💚
223+
Make sure to create another GitHub/GitLab OAuth app that redirects to your local dev server (usually <http://localhost:3000>).

‎docs/content/docs/9.studio/3.providers.md‎

Lines changed: 13 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,14 @@
11
---
22
title: Oauth Providers
3-
description: Configure OAuth providers and synchronizes content between your production website and your Git repository.
3+
description: Configure OAuth providers and synchronizes content between your production website and your GitHub or GitLab repository.
44
navigation:
55
title: Providers
66
seo:
77
title: Git Integration with Studio
88
description: Configure GitHub or GitLab OAuth and synchronizes content between your production website and your Git repository.
99
---
1010

11-
::prose-note
12-
After initial OAuth setup, synchronization happens automatically and requires no manual action.
13-
::
14-
15-
## OAuth Providers
16-
17-
Nuxt Studio supports authentication with both GitHub and GitLab OAuth providers.
18-
19-
### GitHub OAuth App
11+
## GitHub
2012

2113
To use GitHub as your Git provider, you need to create a GitHub OAuth application.
2214

@@ -50,7 +42,11 @@ STUDIO_GITHUB_CLIENT_SECRET=<your_github_client_secret>
5042
```
5143
::
5244

53-
### GitLab OAuth App
45+
::tip
46+
That's it! Once deployed with the appropriate credentials set as environment variables. Studio will be accessible from your production instance. Just login on the `/_studio` (or on the route you've configured) to start editing.
47+
::
48+
49+
## GitLab
5450

5551
To use GitLab as your Git provider, you need to create a GitLab OAuth application.
5652

@@ -79,8 +75,8 @@ After creating the OAuth application, you'll receive:
7975
Add the GitLab OAuth credentials to your deployment platform's environment variables or in your `.env` file in local
8076

8177
```bash [.env]
82-
STUDIO_GITLAB_CLIENT_ID=<your_gitlab_application_id>
83-
STUDIO_GITLAB_CLIENT_SECRET=<your_gitlab_secret>
78+
STUDIO_GITLAB_APPLICATION_ID=<your_gitlab_application_id>
79+
STUDIO_GITLAB_APPLICATION_SECRET=<your_gitlab_secret>
8480
```
8581
::
8682

@@ -117,10 +113,6 @@ This is useful when you want to review changes on a preview environment before m
117113

118114
Update your `nuxt.config.ts` to target your staging branch.
119115

120-
:::tip
121-
You can use environment variables to manage multiple branches for different environments.
122-
:::
123-
124116
```ts [nuxt.config.ts]
125117
export default defineNuxtConfig({
126118
studio: {
@@ -133,6 +125,10 @@ export default defineNuxtConfig({
133125
})
134126
```
135127

128+
:::tip
129+
You can use environment variables to manage multiple branches for different environments.
130+
:::
131+
136132
### Deploy
137133

138134
Configure your hosting platform to deploy the staging branch to a preview URL (e.g., `staging.yourdomain.com`).

0 commit comments

Comments
 (0)