Skip to content

Commit 3446cf3

Browse files
joyeecheungaduh95
joyeecheung
authored and
aduh95
committed
doc: update devcontainer.json and add documentation
The previous .devcontainer.json configuration was outdated and contained personal configurations that were not needed to run a dev container. This updates the structure so that it's put in .devcontainer/base/devcontainer.json based on the recommended setup in GitHub's documentation. The official image now publishes both arm64 and amd64 images, and devcontainer tools should be able to pick up the right one without extra arguments. This also adds documentation on how to use the container. Refs: https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#devcontainerjson PR-URL: #60472 Refs: https://github.com/nodejs/devcontainer Refs: https://hub.docker.com/r/nodejs/devcontainer Reviewed-By: Tierney Cyren <hello@bnb.im> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
1 parent ca8934f commit 3446cf3

File tree

5 files changed

+153
-26
lines changed

5 files changed

+153
-26
lines changed

‎.devcontainer.json‎

Lines changed: 0 additions & 25 deletions
This file was deleted.

‎.devcontainer/base/devcontainer.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"name": "Node.js Dev Container",
3+
"image": "nodejs/devcontainer:nightly",
4+
"workspaceMount": "source=${localWorkspaceFolder},target=/home/developer/nodejs/node,type=bind,consistency=cached",
5+
"workspaceFolder": "/home/developer/nodejs/node",
6+
"remoteUser": "developer",
7+
"mounts": [
8+
"source=node-devcontainer-cache,target=/home/developer/nodejs/node/out,type=volume"
9+
],
10+
"postCreateCommand": "git restore-mtime"
11+
}

‎.github/CODEOWNERS‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,3 +231,7 @@
231231

232232
# userland-migrations
233233
/doc/api/deprecations.md @nodejs/userland-migrations
234+
235+
# dev container
236+
/.devcontainer/* @nodejs/devcontainer
237+
/doc/contributing/using-devcontainer.md @nodejs/devcontainer

‎.gitignore‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@
77
.*
88
# Exclude specific dotfiles that we want to track.
99
!deps/**/.*
10-
!.devcontainer.json
1110
!test/fixtures/**/.*
1211
!.clang-format
1312
!.cpplint
@@ -167,3 +166,10 @@ __pycache__
167166

168167
# === Rules for C++ development ===
169168
compile_commands.json
169+
170+
# === Dev Container rules ===
171+
# Only track the shared base devcontainer.json; ignore everything else under .devcontainer
172+
!.devcontainer/
173+
.devcontainer/**
174+
!.devcontainer/base/
175+
!.devcontainer/base/devcontainer.json

‎doc/contributing/using-devcontainer.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Developing Node.js using Dev Containers
2+
3+
Node.js publishes a [nightly image on DockerHub](https://hub.docker.com/r/nodejs/devcontainer) for
4+
[Dev Containers](https://containers.dev/) that can be used to spin up a
5+
development container that comes with pre-installed build dependencies and pre-genreated build cache.
6+
7+
When you need to test a few changes in the main branch and do not need
8+
to change the V8 headers (which is rare), using the nightly image will allow you to compile your
9+
changes from a fresh checkout quickly without having to compile the entire codebase, especially V8,
10+
from scratch.
11+
12+
The Dev Container also allows you to test your changes in a different operating system, and to test
13+
third-party code from bug reports safely with your work-in-progress Node.js branches in an isolated environment.
14+
15+
There are many command line tools, IDEs and services that [support Dev Containers](https://containers.dev/supporting).
16+
Among them, [Visual Studio Code (VS Code)](https://code.visualstudio.com/) is a very popuplar option.
17+
This guide will walk you through the steps to set up a Dev Container for Node.js development using VS Code.
18+
You should be able to use the same [`nodejs/devcontainer:nightly` image](https://hub.docker.com/r/nodejs/devcontainer)
19+
in other tools and services using generally similar steps.
20+
21+
## Prerequisites
22+
23+
Before you begin, ensure you have the following installed on your machine:
24+
25+
* [Docker](https://www.docker.com/get-started)
26+
* [Visual Studio Code](https://code.visualstudio.com/)
27+
* [Dev Containers extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
28+
29+
## Setting Up the Dev Container
30+
31+
### 1. Clone the Node.js Repository
32+
33+
If you haven't already, clone the Node.js repository to your local machine.
34+
35+
```bash
36+
git clone https://github.com/nodejs/node.git
37+
```
38+
39+
Or follow [this guide](./pull-requests.md#setting-up-your-local-environment) if you are
40+
setting up the git repository to contribute changes as pull requests.
41+
42+
### 2. Open the Repository in VS Code
43+
44+
Launch VS Code and open the cloned Node.js repository.
45+
46+
### 3. Start the Dev Container
47+
48+
* Press `Ctrl+Shift+P` or `Cmd+Shift+P` to open the command palette.
49+
* Type `Dev Containers: Reopen in Container` and select it.
50+
* Select the appropriate Dev Container configuration from the drop down. The base configuration in this
51+
repository is `Node.js Dev Container` located in
52+
[`.devcontainer/base/devcontainer.json`](../../.devcontainer/base/devcontainer.json), which should be
53+
automatically detected by VS Code.
54+
55+
### 4. Wait for the Container to Build
56+
57+
VS Code will build the Dev Container based on the configuration file. This may take some time depending
58+
on your internet connection and system performance.
59+
60+
After the Dev Container is built, it will start automatically. By default it will run `git restore-mtime` to
61+
restore the modification times of the files in the working directory, in order to keep the build cache valid,
62+
and you will see something like this in the terminal.
63+
64+
```text
65+
Running the postCreateCommand from devcontainer.json...
66+
67+
[10136 ms] Start: Run in container: /bin/sh -c git restore-mtime
68+
```
69+
70+
This may take a few seconds. Wait until it finishes before you open a new terminal.
71+
72+
### 5. Build your changes
73+
74+
Once the Dev Container is running, you can open a terminal in VS Code and run the build commands. By default,
75+
your local repository is mounted inside a checkout in the Dev Container, so any changes you make will be reflected
76+
in the container environment.
77+
78+
In the Dev Container, the necessary dependencies are already installed and Node.js has already been
79+
compiled, so a usable cache will exist. For better developer experience, the
80+
build tool used in the Dev Container is `ninja`, instead of `make`. See
81+
[Building Node.js with Ninja](./building-node-with-ninja.md) for more details on using `ninja` to build Node.js.
82+
83+
```bash
84+
./configure --ninja
85+
ninja -C out/Release
86+
```
87+
88+
As long as your local checkout is not too different from the main branch in the nightly image, the build
89+
should be incremental and fast.
90+
91+
### 6. Leaving the Container
92+
93+
When you're done working in the Dev Container, open the command palette again and select
94+
`Dev Containers: Reopen Folder locally` to go back to your local development environment.
95+
96+
## Customizing the Dev Container
97+
98+
The default configuration is located in
99+
[`.devcontainer/base/devcontainer.json`](../../.devcontainer/base/devcontainer.json) which pairs with the
100+
official [Node.js Nightly Dev Container image](https://github.com/nodejs/devcontainer).
101+
This is tracked in version control. You can create a personal configuration by creating a new
102+
directory in `.devcontainer/` and adding a `devcontainer.json` file there (for example,
103+
`.devcontainer/local/devcontainer.json`), and configure VS Code to use it.
104+
105+
## Rebuilding the Dev Container
106+
107+
Docker will cache the already downloaded Dev Container images. If you wish to pull a new nightly image, you can do
108+
so by running the following command in the terminal on your host machine:
109+
110+
```bash
111+
docker pull nodejs/devcontainer:nightly
112+
```
113+
114+
The default configuration creates a volume to cache the build outputs between Dev Container restarts. If you wish to
115+
clear the build cache, you can do so by deleting the volume named `node-devcontainer-cache`.
116+
117+
```bash
118+
docker volume rm node-devcontainer-cache
119+
```
120+
121+
To rebuild the Dev Container in VS Code, open the command palette and select
122+
`Dev Containers: Rebuild and Reopen in Container`.
123+
124+
## Further Reading
125+
126+
* If you want to propose changes to the official Node.js Nightly Dev Container image, feedback is welcome at
127+
[nodejs/devcontainer](https://github.com/nodejs/devcontainer). There, you can find the Dockerfile and
128+
automated nightly workflows.
129+
* [Visual Studio Code Dev Containers Documentation](https://code.visualstudio.com/docs/remote/containers)
130+
* [GitHub's Introduction to Dev Containers](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers)
131+
* [The Dev Containers Specification](https://containers.dev/implementors/spec/)

0 commit comments

Comments
 (0)