Skip to content

Commit 02733b0

Browse files
chadwcarlsonAnouckColson
chadwcarlson
and
AnouckColson
authored
[Next.js] Getting started guide (#3903)
* Reinstate Next.js GS guide. * Doc review --------- Co-authored-by: Anouck Colson <[email protected]>
1 parent 7d00362 commit 02733b0

File tree

1 file changed

+321
-15
lines changed

1 file changed

+321
-15
lines changed

‎sites/upsun/src/get-started/stacks/nextjs.md

Lines changed: 321 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,345 @@
11
---
22
title: Deploying Next.js on Upsun
33
sidebarTitle: Next.js
4-
weight: -95
4+
weight: -97
5+
layout: single
56
description: |
6-
Welcome to the Upsun documentation specific to the Next.js framework on Upsun.
7-
It includes common reference materials useful for deploying Next.js, but also external community and blog resources that cover more advanced topics relevant for the framework.
7+
Complete the last required steps to successfully deploy Next.js on {{% vendor/name %}}.
88
---
99

10-
{{< note title="Hello, there!" theme="info" >}}
10+
{{< note title="Note" theme="info" >}}
1111

12-
{{% description %}}
12+
Before you start, check out the [{{% vendor/name %}} demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/get-started/here/_index.md).
13+
They provide all of the core concepts and common commands you need to know before using the materials below.
1314

14-
Before you proceed, be sure to checkout the [{{% vendor/name %}} demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/get-started/here/_index.md). These two resources provide all of the core concepts and common commands you'll need to know before using the materials below.
15+
{{< /note >}}
16+
17+
{{% guides/requirements name="Next.js" %}}
18+
19+
## 1. Create a Next.js app
20+
21+
To create your Next.js app, follow these steps.
22+
23+
1. Follow the Next.js [installation guide](https://nextjs.org/docs/getting-started/installation).
24+
To fast track the process, run the following commands:
25+
26+
```bash {location="Terminal"}
27+
npx create-next-app@latest
28+
```
29+
30+
2. To initialize the local Git repository and commit local files, run the following commands:
31+
32+
```bash {location="Terminal"}
33+
cd my-app
34+
git init
35+
git add .
36+
git commit -m "Init Next.js application."
37+
```
38+
39+
{{< note theme="info" >}}
40+
You can view the running app locally by running `npm run dev`.
41+
{{< /note >}}
42+
43+
## 2. Create a new project
44+
45+
To create a project on {{% vendor/name %}},
46+
follow these steps.
47+
48+
{{< note title="Remember" >}}
49+
After creating your {{% vendor/name %}} project, copy your new **project ID** for later use.
50+
{{< /note >}}
51+
52+
{{< codetabs >}}
53+
+++
54+
title=Using the CLI
55+
+++
56+
To create a new project with the {{% vendor/name %}} CLI, use the following command and follow the prompts:
57+
58+
```bash {location="Terminal"}
59+
{{% vendor/cli %}} project:create
60+
```
61+
62+
{{< note >}}
63+
64+
When creating a new project using the {{% vendor/name %}} CLI command `project:create`,
65+
you are asked if you want to set the local remote to your new project. Enter **Yes (y)**.
66+
67+
Your local source code is automatically linked to your newly created {{% vendor/name %}} project
68+
through the creation of a `.{{% vendor/cli %}}/local/project.yaml`.
69+
This file contains the corresponding `<projectId>` for the {{% vendor/name %}} CLI to use,
70+
and sets a Git remote to `{{% vendor/cli %}}`.
71+
72+
{{< /note >}}
73+
74+
<--->
75+
+++
76+
title=Using the Console
77+
+++
78+
79+
1. Create an organization or select an existing one.
1580

81+
2. Click **Create from scratch**.
82+
83+
3. Fill in details like the project name and [region](/development/regions.md).
84+
85+
{{% note %}}
86+
87+
You can define resources for your project later on, after your first push.
88+
89+
{{% /note %}}
90+
91+
4. To link your local source code to your new {{% vendor/name %}} project,
92+
run the following command:
93+
94+
```bash {location="Terminal"}
95+
{{% vendor/cli %}} project:set-remote <projectId>
96+
```
97+
98+
This command adds a new remote called `{{% vendor/cli %}}` to your local Git repository,
99+
which is equivalent to the following commands:
100+
101+
```bash {location="Terminal"}
102+
git remote
103+
origin
104+
{{% vendor/cli %}}
105+
```
106+
107+
It also creates a new `.{{% vendor/cli %}}/local/project.yaml` file that contains the `<projectId>`
108+
for the `{{% vendor/cli %}}` CLI to use.
109+
110+
{{< note theme="info" title="Tip" >}}
111+
112+
If you forget your `<projectId>`, run the following command and find your project in the list:
113+
114+
```bash {location="Terminal"}
115+
{{% vendor/cli %}} project:list
116+
```
117+
{{< /note >}}
118+
119+
{{< /codetabs >}}
120+
121+
## 3. Choose your Git workflow
122+
123+
You can use {{% vendor/name %}} projects as a classic Git repository,
124+
where you are able to push your source code in different ways,
125+
using either the Git CLI or the {{% vendor/name %}} CLI.
126+
You can choose which way —or Git workflow— you want to use for your project from the following options:
127+
128+
- Your project source code is **hosted on a {{% vendor/name %}} Git repository**
129+
- Your project source code is **hosted on your own GitHub repository**
130+
131+
{{< codetabs >}}
132+
+++
133+
title={{% vendor/name %}} Git repository
134+
+++
135+
For the rest of this guide, you will use the normal Git workflow (`git add . && git commit -m "message" && git push {{% vendor/cli %}}`) to commit your source code changes to Git history.
136+
You will also use the {{% vendor/name %}} CLI to deploy your [{{% vendor/name %}} environment](/environments.html) with the latest code updates.
137+
138+
<--->
139+
+++
140+
title=GitHub repository
141+
+++
142+
{{% vendor/name %}} provides a [Github integration](integrations/source/github.md) that allows your {{% vendor/name %}} project to be fully integrated with your Github repository.
143+
This enables you, as a developer, to use a normal Git workflow (`git add . && git commit -m "message" && git push`) to deploy your environment—with no need to connect to the {{% vendor/name %}} Console.
144+
145+
{{< note >}}
146+
Make sure you complete the following steps before adding a [Github integration](integrations/source/github.md):
147+
148+
1. Create a Git repository in your own organization following the relevant
149+
[Github repository creation guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
150+
151+
2. Create a [Github integration](integrations/source/github.md).
152+
153+
3. Add a Git remote to your local project, from the root of your Next.js directory.</br>
154+
To do so, run the following commands:
155+
156+
```bash {location="Terminal"}
157+
git remote add origin <urlOfYourOwnGitHubRepo>
158+
git add . && git commit -m "init next.js"
159+
git push origin
160+
```
16161
{{< /note >}}
17162

18-
## Getting started
163+
{{< /codetabs >}}
164+
165+
## 4. Configure your project
19166

20-
- [Upsun demo application](https://console.upsun.com/projects/create-project)
21-
- [Upsun Getting started guide](/get-started/here/_index.md)
22-
- [What is Upsun?](/learn/overview)
167+
To host your Next.js application on {{% vendor/name %}},
168+
you need to have a few YAML configuration files at the root of your project.
169+
These files manage your app's behavior.
170+
They are located in a `.{{% vendor/cli %}}/` folder at the root of your source code
171+
and structured in a similar way to this:
23172
24-
## Documentation
173+
```txt
174+
my-express-app
175+
├── .{{% vendor/cli %}}
176+
│ └── config.yaml
177+
├── [.environment]
178+
└── <project sources>
179+
```
180+
181+
To generate these files, run the following command at the root of your project:
182+
183+
``` {location="Terminal"}
184+
{{% vendor/cli %}} project:init
185+
```
186+
187+
Follow the prompts.
188+
189+
To commit your new files, run the following commands:
190+
191+
```bash {location="Terminal"}
192+
git add .
193+
git commit -m "Add {{% vendor/name %}} config files"
194+
```
195+
196+
## 5. Deploy
197+
198+
And just like that, it’s time to deploy!
199+
200+
Depending on the Git workflow you chose at the beginning of this tutorial,
201+
there are two ways to deploy your source code changes.
202+
203+
{{< codetabs >}}
204+
205+
+++
206+
title=Using {{% vendor/name %}} Git repository
207+
+++
208+
209+
You can push your code using the normal Git workflow (`git add . && git commit -m "message" && git push`).
210+
This pushes your source code changes to your `{{% vendor/cli %}}` remote repository.
211+
Alternatively, you can use the following {{% vendor/name %}} CLI command:
212+
213+
```bash {location="Terminal"}
214+
{{% vendor/cli %}} push
215+
```
216+
217+
<--->
218+
+++
219+
title=Using third-party Git repository
220+
+++
221+
222+
When you choose to use a third-party Git hosting service, the {{< vendor/name >}} Git
223+
repository becomes a read-only mirror of the third-party repository. All your
224+
changes take place in the third-party repository.
225+
226+
Add an integration to your existing third-party repository:
227+
228+
- [BitBucket](/integrations/source/bitbucket.md)
229+
- [GitHub](/integrations/source/github.md)
230+
- [GitLab](/integrations/source/gitlab.md)
231+
232+
If you are using an integration, on each code updates,
233+
use the normal Git workflow (`git add . && git commit -m "message" && git push`) to push your code to your external repository.
234+
To do so, run the following command:
235+
236+
```bash {location="Terminal"}
237+
git push origin
238+
```
239+
240+
Your GitHub, GitLab, or Bibucket integration process then automatically deploys changes to your environment.
241+
If you're pushing a new Git branch, a new environment is created.
242+
243+
{{< /codetabs >}}
244+
245+
{{% vendor/name %}} then reads your configuration files,
246+
and deploys your project using [default container resources](/manage-resources/resource-init.md).
247+
If you don't want to use those default resources,
248+
define your own [resource initialization strategy](/manage-resources/resource-init.md#define-a-resource-initialization-strategy),
249+
or [amend those default container resources](/manage-resources/adjust-resources.md) after your project is deployed.
250+
251+
Et voilà, your Next.js application is live!
252+
253+
{{< note title="Tip" theme="info" >}}
254+
255+
Each environment has its own domain name.
256+
To open the URL of your new environment, run the following command:
257+
258+
```bash {location="Terminal"}
259+
{{% vendor/cli %}} environment:url --primary
260+
```
261+
{{< /note >}}
262+
263+
## 6. Make changes to your project
264+
265+
Now that your project is deployed, you can start making changes to it.
266+
For example, you might want to fix a bug or add a new feature.
267+
268+
In your project, the `main` branch always represents the production environment.
269+
Other branches are for developing new features, fixing bugs, or updating the infrastructure.
270+
271+
To make changes to your project, follow these steps:
272+
273+
1. Create a new environment (a Git branch) to make changes without impacting production:
274+
275+
```bash {location="Terminal"}
276+
{{% vendor/cli %}} branch feat-a
277+
```
278+
279+
This command creates a new local `feat-a` Git branch based on the main Git branch,
280+
and activates a related environment on {{< vendor/name >}}.
281+
The new environment inherits the data (service data and assets) of its parent environment (the production environment here).
282+
283+
2. Make changes to your project.
284+
For example, edit the `views/index.jade` file and make the following changes:
285+
286+
```diff
287+
diff --git a/views/index.jade b/views/index.jade
288+
index 3d63b9a..77aee43 100644
289+
--- a/views/index.jade
290+
+++ b/views/index.jade
291+
@@ -2,4 +2,4 @@ extends layout
292+
293+
block content
294+
h1= title
295+
- p Welcome to #{title}
296+
+ p Welcome to #{title} on Upsun
297+
``
298+
299+
3. Commit your changes:
300+
301+
```bash {location="Terminal"}
302+
git add views/index.jade
303+
git commit -m "Update index page view."
304+
```
305+
306+
4. Deploy your changes to the `feat-a` environment:
307+
308+
```bash {location="Terminal"}
309+
{{% vendor/cli %}} push
310+
```
311+
312+
5. Iterate by changing the code, committing, and deploying.
313+
When satisfied with your changes, merge them to the main branch,
314+
and remove the feature branch:
315+
316+
```bash {location="Terminal"}
317+
{{% vendor/cli %}} merge
318+
Are you sure you want to merge feat-a into its parent, main? [Y/n] y
319+
{{% vendor/cli %}} checkout main
320+
git pull {{% vendor/cli %}} main
321+
{{% vendor/cli %}} environment:delete feat-a
322+
git fetch --prune
323+
```
324+
325+
Note that deploying to production is fast because the image built for the `feat-a` environment is reused.
326+
327+
For a long running branch, to keep the code up-to-date with the main branch, use `git merge main` or `git rebase main`.
328+
You can also keep the data in sync with the production environment by using `{{% vendor/cli %}} env:sync`.
329+
330+
## Further resources
331+
332+
### Documentation
25333
26334
- [JavaScript/Node.js documentation](/languages/nodejs/)
27335
- [Managing dependencies](/languages/nodejs#dependencies)
28336
29-
## Community content
337+
### Community content
30338
31339
- [Next.js topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93&query=nextjs)
32340
- [Node.js topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93&query=node)
33341
- [JavaScript topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93&query=js)
34342
35-
## Blogs
343+
### Blogs
36344
37345
- [A quick-start guide on hosting Next.js on Upsun](https://upsun.com/blog/setting-up-next-js-on-upsun/)
38-
39-
<!-- ## Video -->

0 commit comments

Comments
 (0)