Build and deploy

Building the application

Building a gg application can be done using the gg-CLI. It's as easy as running one command.

$ gg build

If you are in a different directory than your code is, you can pass the name of the directory as argument.

$ gg build path/to/my/app

When building the application, gg copies all static assets into a directory called .build. For pages inside the src directory there are three possible outcomes:

• If the page uses external data (i.e. if it has a getData function) then the page is not compiled to HTML. The filename of the page (in the src directory) is stored so that gg knows which page to compile at run-time.
• Else if the page is a dynamic page, then the page will be compiled to HTML, but it won't be stored in an .html file. Instead, the HTML is stored together with information about which paths will match that page. In the case of a path match at run-time, gg will then return the pre-compiled HTML.
• Else, i.e. if the page is neither dynamic nor does it use external data, the page will be compiled to HTML at build-time, and the result will be stored in an index.html file. The relative path to the file in the .build directory will be the same as in the src directory.

Serving in production mode

After building the application, you can start the production server by using the gg-CLI again.

$ gg start

Also here you can optionally pass the directory in which your code lies as argument.

Take note of the following if your application has pages that use external data:

• Not just the .build directory but also all the source files need to be available in the environment that you run the server. That is because the pages using external data will be compiled at runtime, therefore using the original source code.
• The source files are type-checked again before the server starts running, thus - depending on the number of pages - starting the server can take some time.

Deploying to Vercel

gg applications are built for serverless. For the start, we support deploying a gg application to Vercel in all its glory. That means it supports static pages compiled at build-time as well as dynamic pages and pages using external data compiled at run-time, which are then served by a serverless function.

The gg-CLI allows you to easily add all the files you need to deploy a gg application to Vercel. Just run the init-command again, this time passing it the --vercel flag.

$ gg init --vercel

This will create two additional files:

• A vercel.json configuration file for Vercel
• A file api/gg.ts that will become a serverless function serving pages that use external data and dynamic pages

Note that the actual contents of the latter file are replaced at build-time by the custom vercel-gg runtime. (We specify this in the vercel.json.) We need to keep the "placeholder" file around though as we reference its name in the vercel.json config.

You can create a project on Vercel either by using the Vercel CLI, or directly in the browser from your Vercel dashboard. Either way, you need to change some settings in order for the deployment to succeed:

• You need to create two environment variables:
  • GG_VERSION that specifies the version of gg that you are using
  • GG_TOKEN that contains your gg-token
• Change the build command to be
  curl -fsSL "https://gg.thomasheyenbrock.com/code/${GG_TOKEN}/gg@${GG_VERSION}/build.sh" | sh
• Change the output directory to be .build

Once those settings are in place, you can seamlessly deploy your gg application to Vercel using the CLI.

Vercel even gives you continuous deployment out of the box. You just need to connect your project to a git provider, then each push will be automatically deployed.

Static hosting

If you neither have pages that use external data nor dynamic pages, then all pages will be compiled at build-time. That means that you can host the contents of the .build folder as a completely static website.

A lot of providers offer hosting for static files out of the box, some even without charging you anything!

• Amazon S3
• Vercel
• Netlify
• Firebase