https://github.com/weaponsforge/nextjs-v16-template
NextJS v16 app router simple starter template + Docker configs
https://github.com/weaponsforge/nextjs-v16-template
Last synced: 14 days ago
JSON representation
NextJS v16 app router simple starter template + Docker configs
- Host: GitHub
- URL: https://github.com/weaponsforge/nextjs-v16-template
- Owner: weaponsforge
- License: mit
- Created: 2026-02-15T01:32:23.000Z (4 months ago)
- Default Branch: dev
- Last Pushed: 2026-05-02T09:00:46.000Z (about 1 month ago)
- Last Synced: 2026-05-02T11:06:42.526Z (about 1 month ago)
- Language: TypeScript
- Homepage: https://nextjs-v16-template.vercel.app
- Size: 189 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
## nextjs-v16-template
Barebones NextJS v16 React app template using the **App Router** with custom ESLint rules and Docker configurations.
> Next application code lives inside the `/src` directory.
> [!TIP]
> You may use this project as a **GitHub Template** for quick setup.
> Click **Use this template** (upper right), then select **Create a new repository**
## 📋 Requirements
1. NodeJS (recommended: >= 24.11.0)
```
node: 24.11.0
npm: 11.6.1
```
2. Docker (optional)
## 📦 Core Libraries / Frameworks
This app uses the following libraries and frameworks
| Library | Version | Description |
| --- | --- | --- |
| Next | 16.2.0 | A React framework |
| React | 19.2.4 | Library for creating reusable/composable and interactive components |
| Tailwind CSS | 4.2.1 | Generic, composable utility classes for CSS styling |
| ESLint | 9+ | Enforces coding formats, rules and preferences |
## 🛠️ Installation
#### 1. Clone this repository or your fork/template.
```sh
git clone https://github.com/weaponsforge/next-v16-template.git
```
#### 2. Install dependencies.
```sh
cd nextapp
npm install
```
#### 3. Create a `.env.local` file from the `.env.example` file inside the `/nextapp` directory.
> ⚠️ Ensure only one of `IS_BUILD_STATIC` or `IS_BUILD_DOCKER` has a value of `1` to avoid build conflicts.
| Variable | Description |
| --- | --- |
| IS_BUILD_DOCKER | If value is `1`, builds the NextJS app for Docker in production using the standalone mode build into the `/nextapp/.next/standalone` and `/nextapp/.next/static` directories. |
| IS_BUILD_STATIC | If value is `1`, builds and exports the NextJS app into a static build in the `/nextapp/out` directory when running `"npm run build"`.
⚠️ Next.js apps that use heavy React Server Components (RSC) and Next.js server features will fail to build as a static output. Te enable true static export, [adjust necessary settings](https://nextjs.org/docs/app/guides/static-exports) in the `next.config.ts` file and the overall app before export. |
| IS_WEBPACK | Set to `1` to run the app in development mode using **Webpack**.
⭐ **IMPORTANT**: When running the app via **Docker** on Windows OS (`docker compose up`), this must be set to `1` to enable hot reload.|
| WATCHPACK_POLLING | Set to `true` to enable Webpack-based hot reloading when running the app in Docker on Windows. Required because Turbopack hot reload is currently unreliable in this setup (Docker + Windows). |
## 📖 Usage
Using Node
#### 1. Run the React app for local development.
```sh
cd nextapp
npm run dev
```
#### 2. Launch the local app website in a web browser at:
```
http://localhost:3000
```
#### 3. Edit the source code and wait for changes to display in the web browser.
View the [STRUCTURE.md](/docs/STRUCTURE.md) for guidance on how to structure project folders and files within this project.
#### 4. To build the React app
- For [static export](https://nextjs.org/docs/app/getting-started/deploying#static-export) (only frontend HTML/CSS/JS), set the environment variables `IS_BUILD_STATIC=1` and `IS_BUILD_DOCKER=0`.
- For [Docker standalone mode](https://nextjs.org/docs/app/getting-started/deploying#docker), set the environment variables `IS_BUILD_STATIC=0` and `IS_BUILD_DOCKER=1`.
- Run
```sh
npm run build
```
- This command exports the build artifacts to the `/nextapp/out` directory for **STATIC EXPORT** (`IS_BUILD_STATIC=1`).
- This command exports the build artifacts to the `/nextapp/.next/standalone ` and `/nextapp/.next/.static` directories for **DOCKER STANDALONE MODE** (`IS_BUILD_DOCKER=1`).
## ⚡Alternate Usage
> [!TIP]
> Set `IS_WEBPACK=1` and `WATCHPACK_POLLING=true` to enable hot reloading in development mode when running in Docker on Windows, as Turbopack is currently unreliable in this setup.
Using Docker
Usage with Docker is an alternate option to using Node directly from the [Usage](#-usage) section.
> **IMPORTANT**
> Ensure that port `3000` is free before proceeding.
### Build the Development Docker Image
#### 1. Set up the environment variables for the `/nextapp` directory.
- Refer to the [Installation](#️-installation) section **# 3** for more information.
#### 2. Build the image for local development.
```sh
docker compose build --no-cache
```
> 💡 **INFO:** Do this step only once during initial installation. Re-run this step if there will be changes to the Dockerfile or after installing new Node libraries.
#### 3. Run the container for local development.
```sh
docker compose up
```
#### 4. Launch the local app website in a web browser at:
```
http://localhost:3000
```
#### 5. Edit the source code and wait for changes to display in the web browser.
### Other Docker Builds
1. **`docker-compose.prod.yml`** - packages the NextJS app into a standalone mode for Docker NextJS (app router) deployment.
> Outputs build files in the `/nextapp/.next/standalone` and `/nextapp/.next/.static` directories.
2. **`docker-compose.static.yml`** - packages the frontend-only NextJS app into a static export.
> Outputs build files in the `/nextapp/out` directory.
## 📜 Available Scripts
These scripts, compatible with running in Node and Docker, run various TypeScript scripts and tests.
👉 Click to expand the list of available scripts
### `npm start`
Runs the NextJS app in production mode. Requires running `"npm run build"` first.
### `npm run dev`
- Runs the NextJS app in development mode with hot-reload using Turbopack and NodeJS.
- Set `IS_WEBPACK=1` then run `"docker compose up"` to run the NextJS app in development mode with hot-reload using Docker from a Windows host.
### `npm run build`
Builds the NextJS app for production mode.
> ⚠️ **WARNING**: Ensure only one of `IS_BUILD_STATIC` or `IS_BUILD_DOCKER` has a value of `1` to avoid build conflicts.
- **Static export**
When `IS_BUILD_STATIC=1`: exports the frontend-only build artifacts to the `/nextapp/out` directory.
>⚠️ **NOTE**: Next.js apps that use Next.js server features will fail to build as a **static output**. Te enable true static export, [adjust necessary settings](https://nextjs.org/docs/app/guides/static-exports) in the `next.config.ts` file and the overall app before export.
- **Docker standalone mode**
When `IS_BUILD_DOCKER=1`: exports the NextJS app (uses app router) build artifacts to the `/nextapp/.next/standalone ` and `/nextapp/.next/.static` directories for Docker deployment.
> ℹ️ **INFO**: See the `"npm run docker:build"` script to build the NextJS app for production mode using Docker (NextJS standalone mode build).
### `npm run lint`
Lints TypeScript source codes and files, checking for linting errors.
### `npm run lint:fix`
Fixes lint errors.
### `npm run types:check`
- Checks for TS type errors by generating run-time next-specific types via `"next typegen"` first.
## 📦 Docker Scripts
These scripts are called within the `Dockerfile` for building images.
👉 Click to expand the list of available scripts
### `npm run docker:webpack`
- Runs the NextJS app in development mode inside Docker using Webpack and NodeJS.
- Requires `IS_WEBPACK=1` in `.env.local`.
- Uses the `docker-compose.yml` Docker compose file.
> 💡 **NOTE**: To enable hot reloading, set `WATCHPACK_POLLING=true` in `.env.local`. This is required because Turbopack hot reload is not yet reliable for Next.js apps running in Docker on Windows.
### `npm run docker:build`
- Sets `IS_BUILD_DOCKER=1` and builds a Docker image containing a standalone NextJS build.
- Uses the `docker-compose.prod.yml` Docker compose file.
### `npm run docker:static`
- Sets `IS_BUILD_STATIC=1` and builds a Docker image containing a NextJS static export.
- Uses the `docker-compose.static.yml` Docker compose file.
> 💡 **INFO**: When running `docker compose up`
>
> You can also run `docker exec -it weaponsforge-next-v16-template-dev npm run docker:static` to build a static output.
## References
- Next (Turbopack) currently doesn't work in Docker [[1]](https://github.com/ymeskini/ai-app/issues/1)
@weaponsforge
20260216
20260403