The traps when Nuxt3 with SSG on GitHubPages

We need some additional settings when we are using Nuxt3 on GitHubPages.
And, As you already know, we need to use SSG function of Nuxt3 because GitHub Pages is a static site hosting service.

[Environment]
node: v20
nuxt: 3
os: windows11

using SSG(Static Site Generation)

• generate static files by Nuxt's command

> npm run generate

Then, in the directory ".output/public", static files are generated.

note: quick testing.
We can check the static files on Browser by using the "Live Server" which is Extension of VSCode.

• open the "public" directory on VSCode.
• start the "Live Server".
• access to "http://127.0.0.1:5500/" with Browser.

The traps you must treat

treat the "_nuxt" directory
GitHub Pages uses jekyll as default, and it couldn't read files in "_nuxt" directory.
So we need to make jekyll disabled by putting the ".nojekyll" file at the root directory of the public directory of GitHub Pages.
It is enough that ".nojekyll" is an empty file.

    repository-name/.nojekyll

treat Base URL
When we didn't use a custom domain on GitHub Pages, files are published on this URL below.

https://<username>.github.io/<repository-name>

So we need to set "baseURL" in "nuxt.config.ts".

export default defineNuxtConfig({
.....
    app: {
        baseURL: '/repository-name/',
    }
.....
}

The traps you might need to treat

When we used "app.head" setting in "nuxt.config.ts" for importing outer javascript-files, we need to set base-url manually.

export default defineNuxtConfig({
.....
  app: {
    head: {
      script: [
        {
          src: '/repository-name/***.js',
          // valid options are: 'head' | 'bodyClose' | 'bodyOpen'
          tagPosition: 'bodyClose'
        },
      ]
    },
  }
.....
}

In this way, we need to modify the setting in "nuxt.config.ts" manually when we change the repository name for some reason.
So I think that these way below is better.

1. get the "baseURL" set in Nuxt3 by useRuntimeConfig()

   const runtimeConfig = useRuntimeConfig();
   console.log("runtimeConfig.app.baseURL:");
   console.log(runtimeConfig.app.baseURL);
   

2. use the "useHead()" function in each page for importing outer javascript-files.
   For now, I haven't tried "useHead()" yet. So I'm not sure about the details of settings. but I think "useHead()"will help us.

   useHead({});
   

   In this case, set the "runtimeConfig.app.baseURL" as base-url.

treat "p5.js"

• treat loadFont()
  When we used "loadFont()" function of "p5.js" for importing FontFile, we need to set base-url.
  　
  note: We can use "runtimeConfig.app.baseURL" as base-url, as I mentioned.

  // script in "p5.js"
  loadFont('/repository-name/FONT_NAME.ttf');
  text("ABC, some Text", 10, 10);
  

• treat drawingContext()
  If you use "drawingContext()" in the script of "p5.js"
  and call the function of "HTML5 Canvas" directly
  and import FontFile,
  you need to set base-url.
  　
  note: We can use "runtimeConfig.app.baseURL" as base-url, as I mentioned.

  <script lang="ts">
  import P5 from "p5";
  
  const sketch = (p5: P5) => {
      let isFontloaded: boolean = false;
  
      p5.preload = () => {
          html_fontFile = new FontFace("FONT_NAME", 'url(/repository-name/FONT_NAME.ttf)');
          document.fonts.add(html_fontFile);
          html_fontFile.load().then(() => {
              isFontloaded = true;
          });
      }
  
      p5.setup = () => {
          cnv = p5.createCanvas(***, ***);
          ...
      }
  
      p5.draw = () => {
          if (isFontloaded) {
              cnv.drawingContext.font = `20px "FONT_NAME"`;
              cnv.drawingContext.fillText("ABC, some Text", 10, 10);
          }
      }
  }
  
  </script>