GitLab Pages public folder

Follow these instructions to configure the public folder for the following frameworks.

Eleventy

For Eleventy, you should do one of the following:

• Add the --output=public flag in the Eleventy build commands, for example:

  npx @11ty/eleventy --input=path/to/sourcefiles --output=public

• Add the following to your .eleventy.js file:

  // .eleventy.js
  module.exports = function(eleventyConfig) {
    return {
      dir: {
        output: "public"
      }
    }
  };

Astro

By default, Astro uses the public folder to store static assets. For GitLab Pages, rename that folder to a collision-free alternative first:

1. In your project directory, run:

   mv public static

2. Add the following to your astro.config.mjs. This code informs Astro about our folder name remapping:

   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   
   export default defineConfig({
     // GitLab Pages requires exposed files to be located in a folder called "public".
     // So we're instructing Astro to put the static build output in a folder of that name.
     outDir: 'public',
   
     // The folder name Astro uses for static files (`public`) is already reserved
     // for the build output. So in deviation from the defaults we're using a folder
     // called `static` instead.
     publicDir: 'static',
   });

SvelteKit

When using adapter-static, add the following to your svelte.config.js:

// svelte.config.js
import adapter from '@sveltejs/adapter-static';

export default {
  kit: {
    adapter: adapter({
      pages: 'public'
    })
  }
};

Next.js

With the release of Next.js 13 a lot has changed on how Next.js works. It is recommended to use the following next.config.js so all static assets can be exported properly:

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  images: {
    unoptimized: true,
  },
  assetPrefix: "https://example.gitlab.io/namespace-here/my-gitlab-project/"
}

module.exports = nextConfig

An example .gitlab-ci.yml can be as minimal as:

deploy-pages:
  before_script:
    - npm install
  script:
    - npm run build
    - mv out/* public
  pages: true  # specifies that this is a Pages job
  artifacts:
    paths:
      - public

The previous YAML example uses user-defined job names.

Nuxt.js

By default, Nuxt uses the public folder to store static assets. For GitLab Pages, rename the public folder to a collision-free alternative first:

1. In your project directory, run:

   mv public static

2. Add the following to your nuxt.config.js:

   export default {
     target: 'static',
     generate: {
       dir: 'public'
     },
     dir: {
       // The folder name Nuxt uses for static files (`public`) is already
       // reserved for the build output. So in deviation from the defaults we're
       // using a folder called `static` instead.
       public: 'static'
     }
   }

3. Configure your Nuxt.js application for Static Site Generation.

Vite

Update your vite.config.js to include the following:

// vite.config.js
export default {
  build: {
    outDir: 'public'
  }
}

Webpack

Update your webpack.config.js to include the following:

// webpack.config.js
module.exports = {
  output: {
    path: __dirname + '/public'
  }
};

Should you commit the public folder?

Not necessarily. However, when the GitLab Pages deploy pipeline runs, it looks for an artifact of that name. If you set up a job that creates the public folder before deploy, such as by running npm run build, committing the folder isn’t required.

If you prefer to build your site locally, you can commit the public folder and omit the build step during the job instead.