docker-react

v1.1.0

Published

24 days ago

Tooling to deploy React applications with docker containers.

0High
0Medium
0Low

danielemery

docker react

Docker React

CLI & base image to deploy React applications with docker containers.

Features

[x] Configuration
- [x] Command-line arguments
- [ ] Configuration file
[x] Lightweight nginx docker container
[x] CLI
- [x] Runtime environment variable injection & validation
  - [x] Javascript
  - [ ] HTML
  - [ ] Hash file for cache invalidation
- [x] Application initialization (init / check)
  - [x] index.html file modification
  - [x] Dockerfile generation
  - [x] Schema generation
  - [ ] Types generation
[ ] Support for serving at a path

Supported Tooling

Vite

Supported Validation

Other TODOs

[ ] Example projects
[ ] Cookbook for proxying the container with cloudflare
[ ] Cookbook for handling "in-the-wild" chunks
[ ] Research plugin possibilities with the supported tooling

Out of scope

Server side rendering

Implementation Instructions

The quickest way to set up a consuming project is the init command, which performs most of this setup for you, paired with check, which validates it (and is CI-friendly):

# Scaffold env.schema.js, inject the window.env.js script tag, generate the
# Dockerfile + .dockerignore, and wire the npm scripts. Idempotent — safe to re-run.
npx docker-react init

# Validate that every setup step is complete (non-zero exit on any failure).
npx docker-react check

init performs steps 2–6 below. Steps 1 (install dependencies) and 7 (replace env references in your source) are advisory — init reports what's needed but never runs npm or rewrites your code. check validates all seven steps. Pass --force to overwrite files that have diverged, and --help to see the remaining flags.

The manual steps are documented below for reference and to show what init produces.

Install docker-react and zod (zod version should match the peer dependency version exactly)
```
npm i -S docker-react [email protected]
```
Create environment variable schema (init scaffolds this for you; currently only Zod is supported, others may follow)
The schema is loaded via dynamic import(), so use whichever module syntax matches your project's package.json. CommonJS projects export with module.exports; ESM projects ("type": "module") use export default. (init scaffolds the ESM form.)
```
// env.schema.js (CommonJS)
const { z } = require('zod');

module.exports = z.object({
  VITE_API_URL: z.url(),
});
```
```
// env.schema.js (ESM — "type": "module")
import { z } from 'zod';

export default z.object({
  VITE_API_URL: z.url(),
});
```
Add env import to your index.html head (init injects this for you, before </head>)
```
<head>
  ...
  <script src="/window.env.js"></script>
</head>
```
Create Dockerfile (init generates this for you). NOTE the docker-react image version must match your installed npm version of docker-react — init pins the FROM tag to it automatically.
```
FROM demery/docker-react:vX.X.X

COPY env.schema.js ./env.schema.js
COPY dist /usr/share/nginx/html
```
When generated by init, the build directory is auto-detected from your Vite config's build.outDir (falling back to dist); override it with --build-dir.
Create .dockerignore (init generates this for you)
```
node_modules
```
Update npm scripts (init adds the init-local script and wires it into dev; pass --env-file for the node --env-file variant)
```
{
  "dev": "npm run init-local && vite",
  "init-local": "npx docker-react prep -s ./env.schema.js -d public"
}
```
Note if you are using a .env file the current recommended way is to use node directly.
```
{
  "init-local": "node --env-file=.env ./node_modules/.bin/docker-react prep -s ./env.schema.js -d public"
}
```
There is a pending feature request for npx commands to support loading .env files directly, once it's implemented these docs will be updated accordingly. https://github.com/npm/cli/issues/7069
Replace all references to environment variables with window.env, eg.
- process.env => window.env (for create-react-app and others)
- import.meta.env => window.env (for vite)
(Advisory: init and check report the locations of these references in your src/ but never rewrite your source — you make the replacements.)

Local Testing Instructions

Note: This instructions are to be performed in the consuming application.

# Perform a local production build (using whichever command)
npm run build
# Build a local image tagged with local
docker build -t my-app:local .
# Run local build using the env file
docker run -p 3000:80 --env-file=.env --name=my-app my-app:local

The app should now be available at http://localhost:3000

# Cleanup
docker rm my-app && docker image rm my-app:local

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme