- Run
kool create nextjs my-project
- Run
kool run setup
Yes, using kool + Docker to create and work on new Next.js projects is that easy!
If you haven't done so already, you first need to install Docker and the kool CLI.
Also, make sure you're running the latest version of kool. Run the following command to compare your local version of kool with the latest release, and, if a newer version is available, automatically download and install it.
$ kool self-update
Please note that it helps to have a basic understanding of how Docker and Docker Compose work to use Kool with Docker.
Use the kool create PRESET FOLDER
command to create your new Next.js project:
$ kool create nextjs my-project
Under the hood, this command will run yarn create next-app my-project
to install Next.js using a customized kool Docker image: kooldev/node:20.
After installing Next.js, kool create
automatically runs the kool preset nextjs
command, which helps you easily set up the initial tech stack for your project using an interactive wizard.
$ Preset nextjs is initializing!
? Which javascript package manager do you want to use [Use arrows to move, type to filter]
> npm
yarn
$ Preset nextjs initialized!
Now, move into your new Next.js project:
$ cd my-project
The kool preset
command auto-generated the following configuration files and added them to your project, which you can modify and extend.
+docker-compose.yml
+kool.yml
Now's a good time to review the services added to the docker-compose.yml file.
Say hello to kool.yml, say goodbye to custom shell scripts!
As mentioned above, the kool preset
command added a kool.yml file to your project. Think of kool.yml as a super easy-to-use task helper. Instead of writing custom shell scripts, add your own scripts to kool.yml (under the scripts
key), and run them with kool run SCRIPT
(e.g. kool run npm
). You can add your own single line commands (see npm
below), or add a list of commands that will be executed in sequence (see setup
below).
To help get you started, kool.yml comes prebuilt with an initial set of scripts (based on the preset), including a script called setup
, which helps you spin up a project for the first time.
scripts:
npm: kool exec app npm # or yarn
npx: kool exec app npx
setup:
- kool docker kooldev/node:20 npm install # or yarn install
- kool start
Go ahead and run kool run setup
to start your Docker environment and finish setting up your project:
$ kool run setup
As you can see in kool.yml, the
setup
script will do the following in sequence: runnpm install
to build your Node packages and dependencies (by spinning up and down a temporary Node container); and then start your Docker environment using docker-compose.yml (which includes acommand
to automatically runnpm run dev
).
Once kool run setup
finishes, you should be able to access your new site at http://localhost:3000 and see the Next.js welcome page. Hooray!
You may need to wait a few seconds for Next.js to compile and render the welcome page.
Verify your Docker container is running using the kool status
command:
$ kool status
+---------+---------+------------------------+--------------+
| SERVICE | RUNNING | PORTS | STATE |
+---------+---------+------------------------+--------------+
| app | Running | 0.0.0.0:3000->3000/tcp | Up 5 seconds |
+---------+---------+------------------------+--------------+
Run kool logs app
to see the logs from the running app
container, and confirm the Next.js server was started.
Use
kool logs
to see the logs from all running containers. Add the-f
option afterkool logs
to follow the logs (i.e.kool logs -f app
).
$ kool logs app
Attaching to my-project_app_1
app_1 |
app_1 | > [email protected] dev /app
app_1 | > next dev
app_1 |
app_1 | ready - started server on 0.0.0.0:3000, url: http://localhost:3000
Use kool exec
to execute a command inside a running service container:
# kool exec [OPTIONS] SERVICE COMMAND [--] [ARG...]
$ kool exec app node -v
Try kool run npx next -h
(or kool run yarn next -h
) to execute the kool exec app npx next -h
command in your running app
container and print out information about Next.js CLI commands.
Similar to SSH, if you want to open a Bash session in your app
container, run kool exec app bash
, where app
is the name of the service container in docker-compose.yml. If you prefer, you can use sh
instead of bash
(kool exec app sh
).
$ kool exec app bash
bash-5.1#
$ kool exec app sh
/app #
If you need your app
container to use your local SSH keys to pull private repositories and/or install private packages (which have been added as dependencies in your package.json
file), you can simply add $HOME/.ssh:/home/kool/.ssh:delegated
under the volumes
key of the app
service in your docker-compose.yml file. This maps a .ssh
folder in the container to the .ssh
folder on your host machine.
volumes:
- .:/app:delegated
+ - $HOME/.ssh:/home/kool/.ssh:delegated
When it's time to stop working on the project:
$ kool stop
And when you're ready to start work again:
$ kool start
We have more presets to help you start projects with kool in a standardized way across different frameworks.
Missing a preset? Make a request, or contribute by opening a Pull Request. Go to https://github.com/kool-dev/kool/tree/main/presets and browse the code to learn more about how presets work.