React Developer Container - Docker Setup & Usage Guide

🎯 Introduction

This section describes how to create and start the React developer container, which enables you to immediately begin developing your applications within the container. Since React supports various project types (SPAs, MPAs, static sites, SSR, mobile PWAs, Electron), we will gradually provide additional Docker files to extend the container. The goal is to allow you to choose a project type by selecting the corresponding docker-compose_* file, which will set up the required software and provide you with a template application.

Swarm support

This container supports Docker Swarm. For setup instructions, refer to the PHP Development Template Stack. See this guide and the howto_create_a_swarm link. The procedure is identical, so use that project for details if needed.

🛠️ The Basic React Container Setup

This Docker React container consists of a couple of Dockerfile and Compose combinations. The first setup is needed to install Node.js, which also includes the npx program, allowing us to create a new React project. This step installs the basics, and afterward, we can run another Dockerfile/Compose combination to create the React project.

To Setup the basic React container in docker Desktop execute this command from the [*Service] directory:

 docker-compose -f compose_nodejs_react_cont.yml up -d --build --force-recreate 

Warning: Regenerate the container

When recreating the same container (service name), avoid subtle and annoying caching issues. To prevent irritation, make sure to:

◉ Delete the container
◉ Delete the volume
◉ Use the Docker prune command

docker system prune -a --volumes 

✅ Setup Result

After running this command, you can open a terminal session in the container. By default: - you should be in the projects directory (pwd),

• This directory should be empty (ls). If it is not empty, you may be experiencing caching issues!
• In the root of the container a directory ‘shared-host’ is available which is mapped to the host in the directory: NodeReactWebService\shared-host. Use this to exchange files or create backup of your project (Example: `cp -r /projects/nextjs/myproject /shared-host)

---

⚙️ Creating React projects

This section includes several Dockerfile and Docker Compose combinations that you can choose from to create a startup project. All the procedures in these subsections assume a Windows host, but you should have no trouble adapting them for a Linux host. Also you should first have created the basic react container as described in: The Basic React Container Setup

Warning: Running NPN server

By default you can only start one NPN server with a project in a container, this means that only the last project created will be run with NPN. This can be changed using for example, npn-run-all or using a Process Manager. At the moment this is not part of this container stack!

⚡ creating a React project app using CRA

This will create a basic Node.js traditional React project using the command npx create-react-app(CRA) in combination with React Routing. With this, you can create multiple default projects based on the standard cra-[*] templates. Additionally, there are many community templates available; you can find examples here.The templates supported can be found in the ‘.env’ file. This type of project was declared deprecated since 2023 but is still used a lot, It uses SPA (Single Page Application) which is processed on the client side.

These day Next.js with (default) server page processing is preferred, this will be described in the next paragraph!

Note: Traditional React

The package Next.js (which is preferred these days) can also create a traditional React SPA.React Routing project; see paragraph Creating a React Routing Project Application using Next.js

Create the React application project:

1. Open the file: .env and choose one of the project types to use, remove the comments of one of the PRJ_TYPE_ARG lines
2. In the same .env file, set the variable ‘PRJ_NAME_ARG’ to a value for your project. Optional you can also set the environment variable from the command line, This value will be used for the project name and the project directory.If you omit this step the default will be used (see variable: PRJ_NAME_ARG in the .env file)

   • $env:PRJ_NAME_ARG="my-project"  # From Command line 

3. Then execute the docker command

   • docker  compose -f compose_cra_project.yml up -d  --remove-orphans --build --force-recreate 

     
     

✅ Setup result & possible customization’s

After that you can open a terminal session in your container and you should fine your project at: /projects/prjtype/[my-project]

• The nodeJs server is automatic started with your new created project, In the host you can surf to:

 http://localhost:3002/			# The port can be different 

• In the (container) file: /projects/prjtype/[my-project]/.env You can find the used variables, one of them is the HOST variable, the value 0.0.0.0 indicates that the site is available from any host, thus also our host, defining localhost as value, will have the result that the site is not available from the (Windows) host.
• Also the CONTAINER PORT variable can be found in the .env file change this if you want(no direct need to), and restart the container
  
• You need to using a different HOST PORT? If this is required you need the change the published port in the base compose file:
  • compose_nodejs_react_cont.yml, stop the container and start it with:

 docker-compose -f compose_cra_project.yml up -d 

Warnings: Ports

Warning 1 When you try to restart with Docker Desktop, it will use the old host port!
Warning 2 Make SURE the container port in compose_nodejs_react_cont.yml is the SAME as in .env (/projects/prjtype/[your projects]) otherwise it fails

Limitation! Currently, it is not possible to successfully run this Docker/Compose coordination multiple times with different project names (which was, and still is, the intention). When running it a second time, it creates a new, empty project. I believe this issue is related to Docker caching and the nxp command.
Possible workaround you could try to execute the following command in the projects directory of the container:

npx create-react-app /projects/prjtype/default_project_name --template cra-template

• In .env file in the new directory, make sure to update the container port (should be different than other project) After that start the application with:

 npm start 

⚡ Building a Server-Rendered Next.js App with Automatic Routing (default)

The Next.js React framework package is since ~2023 the new preferred method to create an application. Main changes compared to the default React framework include:

• No manual routing of components needed anymore, as routing is now automatically handled based on files and directory structure
• a page is rendered on the server(Server-Side Rendering) and not on the client, as is the case with client-side rendered React applications. When creating a new application this should be the default choice, unless you have compelling reasons to do otherwise.

⚡ creating a new project

1. In the ‘NodeReactWebService’ sub directory open the file ‘.env’ in that file set:
   • Choose a unique port, this will be used for the container as well as for the host!

    PORT=3098

   • Update the target project name

    PRJ_NAME_ARG_NEXT=my-project 

2. Execute the following:

docker  compose -f compose_nextjs_cust_project.yml up -d  --remove-orphans --build --force-recreate 

✅ Setup result & possible customization’s

• You should be able to open the browser in the host with this (change to your port) And the “React Template Website” should be displayed!

  http://localhost:3098/ 

• In case something seems to be off first try to restart the Docker container!

---

⚡ Creating a React Routing Project App using Next.js

Since 2023, this is the preferred method for creating projects. In this Docker/Compose combination, we will create a project using the traditional React Routing method (the same as in 2.1 using the CRA method). However, this time we will use our own template. Because the Next.js environment does not support the React Routing method (which is characterized by rendering on the client side, while Next.js renders by default on the server), we may need to make some necessary changes in the ClientRouter.js file, where you should add your other Link and Route definitions.

⚡ To create a new project

1. In the ‘NodeReactWebService’ sub directory open the file ‘.env’ in that file set:
   • Choose a unique port, this will be used for the container as well as for the host!

    PORT=3098	

   • Update the target project name

    PRJ_NAME_ARG_NEXT=my-project 

2. Execute the following:

docker  compose -f compose_nextjs_cust_cra_project.yml up -d  --remove-orphans --build --force-recreate

✅ Setup result & possible customization’s

• You should be able to open the browser in the host with this (change to your port) And the “React Template Website” should be displayed!

  http://localhost:3098/ 

• In case something seems to be off first try to restart the Docker container!

---

🗄️ Backup and restore project

You can backup a React project to your host, via the host share, and restore it later (possible in a other directory with running on other port)

• 💾 Backup the project

  • In the directory where the project is execute:

    rsync -av --exclude='node_modules' my-prj/ /shared-host/my-prj
    
    

    • After this the project can be found on the docker directory of your host NodeReactWebService\shared-host\/. you can than move it where ever you like of course.

• 🔄 Restore the project
  To restore use the Power-Shell file: Restore_project.ps1 in combination with the environment variables in .env and follow these steps:

  • Open the file: Restore_project.ps1 to indicate the docker context and the folder to restore are located.
  • Change the variable: $ProjectToDockerContext this must point to your Docker context (where the ‘compose_restore_project.yml’ is located) change the variable: ProjectToRestore this must point to the React project to restore.
  • Optional(but recommenced) set the environment variable in .env
    • Set the base target directory in the container , example: /projects/myweb-sites

      PRJ_BASE_ARG_REST=/projects/myweb-sites  

    • Sets the target project name (dir) in the container, example: /mysite

      PRJ_TARGET_ARG_REST=/mysite	

      The above example results in: /projects/myweb-sites/mysite

  • Set the used port when running

    PORT=3072

  • Finally, run the Power-Shell file:

    ./Restore_project.ps1 

This will call the ‘compose_restore_project.yml’, when the ProjectToRestore directory is found and creates and starts the container with the restored React project.

✅ Result

This should have created the directories as displayed above and the web application should be available at:

http://localhost:3097/ 

---

Develop with VS Code

To develop in Visual Studio Code we advice the following method and Plugins.

Open the container application

We have provide already a ‘settings.json’ file with relevant settings in the .vscode directory these settings will be used when you open\load the container application. The ‘settings.json’ requires some plugins to be installed make sure to install these first.

• Required plugins
  (See code below to install them easily)
  • ESLint
  • Prettier
  • Path Intellisense
  • Bracket Pair Colorizer 2

  • Auto Rename Tag.

    # Install required plugins
    code --install-extension ms-vscode-remote.remote-containers
    code --install-extension dbaeumer.vscode-eslint
    code --install-extension esbenp.prettier-vscode
    code --install-extension christian-kohler.path-intellisense
    code --install-extension coenraads.bracket-pair-colorizer-2
    code --install-extension formulahendry.auto-rename-tag
    

• Optional plugins
  (See code below to install them easily)
  • VS Code Styled Components
  • Jest

  • GitLens

    # Install required plugins
    code --install-extension dbaeumer.vscode-eslint
    code --install-extension esbenp.prettier-vscode
    code --install-extension christian-kohler.path-intellisense
    

▶️ Open the docker React app

• Open Visual Studio Code
• Open the docker Tab on the left
• In ‘Containers’ section, select your container and right click -> ‘Attach Visual Studio Code’
• if the project directory is not opened automatically, choose: ‘Open folder’ and select the folder /projects
  • optional you can select the folder: /projects[type][project name] if you know the name of your project.

Notes: live reload and backup & restore

◉ Changes you make in the code are applied immediately to the running site (live reload), if the site is open in your browser.
◉ Backup & restore: You can download the project to the host and restore it with the Docker restore compose. Before restoring, delete the project’s node_modules and .next directories (they will be regenerated during restore). Do not remove the .vscode folder. See the “Backup and restore project” section for full instructions.

License
This file is part of: React Development Template Stack Copyright (c) 2025-2026 Nico Jan Eelhart.This repository is MIT licensed and free to use. For optional commercial support, customization, training, or long-term maintenance, see COMMERCIAL.md.

─── ✦ ───