Extract quad-shader lib

Author: nmattia

Diff for: .github/workflows/ci.yml

@@ -3,9 +3,8 @@
 name: Deploy static content to Pages
 
 on:
-  # Runs on pushes targeting the default branch
+  # Runs on pushes
   push:
-    branches: main
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -35,11 +34,21 @@ jobs:
       - name: Build
         # Here we set an empty base, which makes vite produce links that are relative
         # to the assets, as opposed to expecting all assets to be served from `/`.
-        run: npm ci && npm run tsc && npm run build -- --base ''
-      - name: Upload artifact
+        run: npm ci && npm run build -- --base ''
+      - name: Upload pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: './dist' # vite's build output
+          path: './dist/pages' # vite's outDir as specified in package.json
+
+        # build the .tgz in ./out and upload as artifact
+      - name: Build library
+        run: mkdir -p ./out && npm pack --pack-destination ./out
+      - name: Upload lib artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './out'
+
       - name: Deploy to GitHub Pages
+        if: github.ref_name == github.event.repository.default_branch
         id: deployment
         uses: actions/deploy-pages@v4

Diff for: HACKING.md

@@ -0,0 +1,31 @@
+# Hacking
+
+This explains how to develop locally, build the app & package the lib.
+
+## Development
+
+Best way to develop is with vite hot-reloading:
+
+```sh
+npm run dev
+```
+
+## Build microsite
+
+Run the production build:
+
+```sh
+npm run build
+```
+
+## Package the library
+
+```
+npm prepare # or npm pack to see the .tgz
+```
+
+or alternatively, publish it:
+
+```
+npm publish
+```

Diff for: README.md

@@ -3,12 +3,12 @@
   <img width=300 height=300 src="https://github.com/user-attachments/assets/52f41567-effd-49a3-90b1-544e19d3e3bc" />
 </p>
 
-# WebGL Shader Template
+# Quad Shader
 
 This serves as a boilerplate for creating WebGL-based applications using
 [Vite](https://vitejs.dev/) and [TypeScript](https://www.typescriptlang.org/).
 You can view the template built and deployed at
-[https://nmattia.github.io/webgl-starter-template/](https://nmattia.github.io/webgl-shader-template/).
+[https://nmattia.github.io/quad-shader/](https://nmattia.github.io/quad-shader/).
 
 Whether you're just getting started with WebGL or looking for a quick way to
 bootstrap your shader projects, this template should serve as a solid
@@ -58,21 +58,19 @@ enabled for your repository (Settings -> Pages -> Source -> GitHub Actions)
 ### Project Structure
 
 ```
-webgl-shader-template/
+quad-shader/
+├── frag.glsl           # Fragment shader (where animation is defined)
 ├── index.html          # Vite entry point & main page
 ├── index.ts            # Demo app/microsite entrypoint
-├── frag.glsl           # Fragment shader (where animation is defined)
-├── public              # Static assets
 └── src
-    ├── lib.ts          # TypeScript module setting up WebGL
-    └── vert.glsl       # Vertex shader (setting up the vertices)
+    └── index.ts        # TypeScript module setting up WebGL
 ```
 
 ### Customizing the Shader
 
-This template includes a basic vertex shader (`src/vert.glsl`) setting up
-4 vertices that the fragment shader draws on. The fragment shader (`frag.glsl`)
-includes an animation that you can remove or tweak to see how your changes affect
+This template includes a basic vertex shader setting up a quad (4 vertices) that
+the fragment shader draws on. The fragment shader (`frag.glsl`) includes an
+animation that you can remove or tweak to see how your changes affect
 what is shown on the screen.
 
 ### Prettier

Diff for: index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/png" href="favicon.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>WebGL Shader Template</title>
+    <title>quad-shader: Render fragment shader in a quad</title>
     <link rel="stylesheet" href="./style.css" />
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
@@ -14,7 +14,7 @@
     />
   </head>
   <body>
-    <h1>WebGL Shader Template</h1>
+    <h1>Easy 2D shader setup with quad-shader</h1>
     <p>
       This is a template for getting started with
       <a
@@ -24,10 +24,10 @@ <h1>WebGL Shader Template</h1>
         >WebGL</a
       >. The code is on GitHub at
       <a
-        href="https://github.com/nmattia/webgl-shader-template"
+        href="https://github.com/nmattia/quad-shader"
         target="_blank"
         rel="noopener noreferrer"
-        >nmattia/webgl-shader-template</a
+        >nmattia/quad-shader</a
       >.
     </p>
     <div id="canvas-container">
@@ -51,7 +51,7 @@ <h1>WebGL Shader Template</h1>
       This template has <strong>no dependencies</strong> and uses the WebGL API
       directly. See more in the GitHub
       <a
-        href="https://github.com/nmattia/webgl-shader-template"
+        href="https://github.com/nmattia/quad-shader"
         target="_blank"
         rel="noopener noreferrer"
         >repository</a

Diff for: index.ts

@@ -1,6 +1,6 @@
 // This is the app's entrypoint. It picks the canvas element and attaches sets up
 // WebGL via the lib.
-import { attach } from "./src/lib";
+import { attach } from "./src";
 
 // Read the .glsl file contents
 import fragShaderSrc from "./frag.glsl?raw";

Diff for: package-lock.json

@@ -1,14 +1,31 @@
 {
-  "name": "webgl-shader-template",
-  "private": true,
+  "name": "quad-shader",
   "version": "0.0.0",
   "type": "module",
+  "files": [
+    "README.md",
+    "LICENSE",
+    "dist/lib/quad-shader.js",
+    "dist/lib/quad-shader.cjs",
+    "dist/types/index.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/lib/quad-shader.js"
+    }
+  },
+  "//scripts": {
+    "dev, build & preview": "build the webapp (e.g. for GitHub Pages deployment)",
+    "types & prepare": "build the lib, to be used by 'npm publish' or 'npm pack'"
+  },
   "scripts": {
     "dev": "vite",
-    "build": "tsc && vite build",
-    "preview": "vite preview",
-    "tsc": "tsc",
-    "format": "prettier ./src ./index.ts ./index.html ./style.css ./package.json -w"
+    "build": "tsc --project tsconfig.json && vite build --config /dev/null --outDir ./dist/pages",
+    "preview": "npm run build && vite preview --outDir ./dist/pages",
+    "prepare": "npm run types && vite build --outDir ./dist/lib",
+    "types": "tsc --project ./tsconfig.lib.json",
+    "format": "prettier ./src ./index.ts ./index.html ./style.css ./package.json vite.config.ts -w"
   },
   "devDependencies": {
     "prettier": "^3.3.3",

Diff for: package.json

@@ -6,10 +6,23 @@
 // uAspectRatio (ratio width/height of the canvas element). For more uniforms, use
 // the `WebGLRenderingContext` returned by `attach` or specify `beforeRender`.
 
-// Read the .glsl file contents
-import vertShaderSrc from "./vert.glsl?raw";
+const vertShaderSrc = `
+attribute vec2 aVertexPosition;
 
-type Opts = {
+uniform float uAspectRatio;
+varying vec2 vPosition;
+
+void main() {
+    // gl_Position is the ouput, which we simply return
+    gl_Position = vec4(aVertexPosition, 0.0, 1.0);
+
+    // We pre-scale the data passed to the fragment shader so that the
+    // fragment shader doesn't have to care about the aspect ratio
+    vPosition = gl_Position.xy * vec2(uAspectRatio, 1.0);
+}
+`;
+
+export type Opts = {
   beforeRender?: (gl: WebGLRenderingContext, state: State) => void;
 };
 
@@ -219,6 +232,7 @@ function resizeIfDimChanged(gl: WebGLRenderingContext, state: State): boolean {
   const pxWidth = clientWidth * window.devicePixelRatio;
   const pxHeight = clientHeight * window.devicePixelRatio;
 
+  // NOTE: the CSS MUST bound the canvas size otherwise this will grow forever
   state.canvas.width = pxWidth;
   state.canvas.height = pxHeight;
 

Diff for: src/lib.ts renamed to src/index.ts

@@ -20,5 +20,5 @@
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true
   },
-  "include": ["src", "index.ts"]
+  "include": ["src", "index.ts", "types.d.ts"]
 }

Diff for: src/vert.glsl

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationDir": "dist/types"
+  },
+  "include": ["src/index.ts" ]
+}

Diff for: tsconfig.json

@@ -0,0 +1,15 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vite";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  build: {
+    copyPublicDir: false /* in the lib we don't care about any assets */,
+    lib: {
+      entry: resolve(__dirname, "src/index.ts"),
+      formats: ["es", "cjs"] /* target modern browsers & node */,
+    },
+  },
+});