Setting up NextJS app in goatbot

Start

Bootstrap NextJS app

If you simply run npx create-next-app you'll have a functioning boilerplate app where everything is SSR-ed by default, with support for Typescript and ESLint. This is a great base and will get you going quickly

Additional things you need

To make the app deployable in GOAT ecosystem you also need to add a couple of non-boilerplate things:

Dockerfile

example
the only non-negotiable is that it runs your app on port 3000
otherwise you can customize as you like
feel free to copy this which is our standard FE docker setup and won't need any modification. Please note this one relies on /bin scripts so you should copy those into your app as well

/healthcheck route that returns 200

example
if you used create-next-app (Next 15) this file will live at /src/app/healthcheck/route.ts
if you don't understand why this file is called route.ts or why it's placed in that location, have a look at Next's routing documentation. it will be helpful when you add more routes and features to your app

`/create-app` in #dev-infra

Publish your repo on Github if you haven't already
Run /create-app <app> command in #dev-infra.
Fill out whatever permissions, etc. are appropriate and submit
Do a test deploy to staging and make sure it all looks good

`/create-site` in #dev-infra

Run /create-site <site> command in dev-infra channel
I forget what happens after this. i think usually it just works

If all went well, your app is now deployable using /deploy <app> to x and you can access it at the URL you configured

Next Steps

Install `@goatapp/*` NPM packages

GOAT NPM libraries are not on the public registry and using them requires a couple of steps

add .npmrc file. this tells npm command it should look on Github for @goatapp prefixed packages, and use the auth token you provide
add GH_PACKAGES_TOKEN as a Repository secret in your Github settings /goatapp/<repo>/settings/secrets/actions
- best to roll an app-specific token every time but honestly i just copy/paste the one from goat-ci bot user in 1Password. for local developlemt you can also use this one or generate your own

Talking to other GOAT apps

Env variables

In a Next app you configure env vars like this. At a minimum you'll want GOATENV_ENVOY_EGRESS but can add others too

GRPC / protobufs

If you're talking to go-services over GRPC you'll

Extras

Above is the minimal case but there are some other things you probably also want to add to the project, for DX and code safety

Developer experience

CI checks

Can use a workflow like this one and make it required for merging PRs

Stagex

StageX is nice because you can easily publish and test experimental app versions. To set it up: go to #dev-infra-requests > Workflows (button at top of channel) > Request: Setup StageX

Automatic staging deploys

Optionally you can have main auto-deploy to staging whenever it changes, which is nice and saves some time. The workflow for this is simple, the hard part is creating a bot deploy user and coordinating with infra to get its deploy key

derryl/Setting up NextJS app in goatbot.md