Yes, using a devcontainer.json file is generally the recommended approach for creating a consistent development environment in GitHub Codespaces.

A dev container configuration allows you to define the tools, extensions, dependencies, and other settings that should be available whenever someone creates a Codespace for the repository.

1. Create a devcontainer.json

You can place the configuration inside:

.devcontainer/devcontainer.json

A basic example could look like:

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  },
  "postCreateCommand": "npm install"
}

This makes sure that the required Node.js environment, VS Code extensions, and project dependencies are available when the Codespace is created.

2. Managing dependencies

It is usually better to keep project dependencies in the project's normal dependency files rather than installing everything manually inside the Codespace.

For example:

Node.js → package.json
Python → requirements.txt or pyproject.toml
Java → pom.xml or build.gradle
Ruby → Gemfile

You can then use postCreateCommand to install them automatically.

For example:

{
  "postCreateCommand": "npm install"
}

3. Installing development tools

If the project requires additional tools, they can be added to the dev container configuration instead of asking every contributor to install them manually.

For example:

{
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  }
}

This helps keep the development environment reproducible across different machines and Codespaces.

4. Environment variables and secrets

Environment variables that are safe to share can be configured through the dev container configuration when appropriate.

However, secrets such as API keys, passwords, and tokens should not be committed to devcontainer.json or any other repository file.

For sensitive values, GitHub Codespaces secrets or another secure secret-management solution should be used.

Instead of committing an actual secret:

API_KEY=actual-secret-value

the application should read the value from an environment variable, while the actual secret is provided securely through the appropriate GitHub settings.

5. Use a Dockerfile when more customization is needed

For simple projects, a predefined development container image may be enough.

For projects requiring custom system packages, specific versions, or additional configuration, you can use a Dockerfile:

.devcontainer/
├── devcontainer.json
└── Dockerfile

For example:

FROM mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm

RUN apt-get update \
    && apt-get install -y \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

Then reference it from devcontainer.json:

{
  "name": "My Project",
  "build": {
    "dockerfile": "Dockerfile"
  }
}

6. Recommended best practices

Some useful practices for Codespaces are:

Keep the configuration inside .devcontainer/ and commit it to the repository.
Pin important tool or runtime versions where reproducibility matters.
Keep application dependencies in the project's standard dependency files.
Avoid hard-coding secrets or credentials in the repository.
Only install the extensions and tools that the project actually needs.
Use postCreateCommand for setup tasks that should happen after the container is created.
Use a custom Dockerfile when predefined development container images are not sufficient.
Keep the dev container configuration simple and easy for other contributors to understand.
Test the configuration by creating a fresh Codespace instead of relying only on an existing environment.
Document any unusual setup requirements in the repository's README.
Example project structure

A typical repository could look like:

my-project/
├── .devcontainer/
│   ├── devcontainer.json
│   └── Dockerfile
├── src/
├── package.json
├── package-lock.json
└── README.md

With this approach, contributors can create a new Codespace and get a predictable development environment without manually installing the same tools and extensions every time.

Overall, devcontainer.json is a good starting point for most Codespaces projects, while a custom Dockerfile can be added when the project needs more control over the underlying development environment.