TypeScript met clasp en Apps Script

Waarom clasp en TypeScript

clasp (Command Line Apps Script Projects) is de officiele CLI van Google waarmee je Apps Script lokaal ontwikkelt. Je schrijft code in je eigen editor, krijgt typeveiligheid en autocompletion via TypeScript en beheert versies met Git. Het resultaat push je met een enkel commando naar Google.

clasp installeren

clasp 3 vereist Node.js 22 of nieuwer. Controleer je versie met node -v en installeer clasp daarna globaal.

npm install -g @google/clasp
clasp login

clasp login opent een browservenster voor de Google-autorisatie. Na akkoord worden je inloggegevens lokaal opgeslagen.

Nieuw project aanmaken

In clasp 3 zijn enkele commando's hernoemd. clasp create-script is de nieuwe naam; het oude clasp create blijft als alias bestaan. Hetzelfde geldt voor clasp clone-script (was clasp clone) en clasp open-script (was clasp open).

mkdir mijn-script && cd mijn-script
clasp create-script --title "Mijn Script" --type standalone
npm init -y
npm install --save-dev @types/google-apps-script typescript esbuild

Maak een tsconfig.json aan. De Apps Script V8-runtime ondersteunt grofweg ES2019, dus dat is een veilig doel:

{
  "compilerOptions": {
    "target": "ES2019",
    "module": "ESNext",
    "lib": ["ES2019"],
    "strict": true,
    "noEmit": true,
    "rootDir": "src"
  },
  "include": ["src/**/*"]
}

noEmit staat hier aan omdat TypeScript zelf alleen typecheckt; het echte bouwen doet de bundler. Wijs in .clasp.json de rootDir naar de map met de gebundelde uitvoer:

{
  "scriptId": "JOUW_SCRIPT_ID",
  "rootDir": "dist"
}

Bundelen met esbuild

esbuild bundelt je TypeScript snel naar een enkel JavaScript-bestand dat Apps Script begrijpt. Maak een build.mjs:

import { build } from 'esbuild';

await build({
  entryPoints: ['src/Code.ts'],
  outfile: 'dist/Code.js',
  bundle: true,
  format: 'iife',
  target: 'es2019',
});

Apps Script verwacht globale functies, dus gebruik format: 'iife' of plaats je entrypoint-functies op het globale bereik. Zorg dat functies die je vanuit triggers of het menu aanroept benaderbaar blijven na het bundelen.

TypeScript-code schrijven

interface Klant {
  id: number;
  naam: string;
  email: string;
  actief: boolean;
}

interface SpreadsheetConfig {
  spreadsheetId: string;
  bladNaam: string;
}

function haalKlantenOp(config: SpreadsheetConfig): Klant[] {
  const ss = SpreadsheetApp.openById(config.spreadsheetId);
  const blad = ss.getSheetByName(config.bladNaam);

  if (!blad) {
    throw new Error(`Blad ${config.bladNaam} niet gevonden`);
  }

  const data = blad.getDataRange().getValues();
  return data.slice(1).map((rij): Klant => ({
    id: Number(rij[0]),
    naam: String(rij[1]),
    email: String(rij[2]),
    actief: Boolean(rij[3]),
  }));
}

function stuurEmail(ontvanger: string, onderwerp: string, body: string): boolean {
  try {
    GmailApp.sendEmail(ontvanger, onderwerp, body);
    return true;
  } catch (e) {
    console.error(`E-mail fout: ${e}`);
    return false;
  }
}

De dagelijkse workflow

Voeg handige scripts toe aan je package.json zodat bouwen en pushen in een stap gaan:

{
  "scripts": {
    "typecheck": "tsc",
    "build": "node build.mjs",
    "push": "npm run build && clasp push",
    "watch": "clasp push --watch"
  }
}

De kerncommando's van clasp gebruik je zo:

npm run build

clasp push

clasp pull

clasp open-script

clasp logs

clasp push uploadt de inhoud van je rootDir naar Google. clasp pull haalt de huidige versie uit Apps Script terug, handig als iemand in de online-editor iets heeft aangepast.

Bestaand project klonen

Heb je al een script in Apps Script (bijvoorbeeld een spreadsheet-gebonden script)? Kloon het lokaal en bouw daaromheen je TypeScript-project op.

clasp clone-script JOUW_SCRIPT_ID

clasp pull

Geheimen en configuratie

Bewaar API-sleutels en andere geheimen niet in je code. In Apps Script gebruik je daarvoor Script Properties; lokaal houd je gevoelige waarden buiten Git via een .env-bestand dat in .gitignore staat.

interface Configuratie {
  apiKey: string;
  apiUrl: string;
  debugMode: boolean;
}

function getConfig(): Configuratie {
  const props = PropertiesService.getScriptProperties().getProperties();
  return {
    apiKey: props['API_KEY'] || '',
    apiUrl: props['API_URL'] || 'https://api.voorbeeld.nl',
    debugMode: props['DEBUG'] === 'true',
  };
}

Enum-typen voor leesbaarheid

Enums maken statuswaarden en logniveaus expliciet en voorkomen typfouten in strings.

enum Status {
  Actief = 'actief',
  Inactief = 'inactief',
  InAfwachting = 'in_afwachting',
}

enum LogNiveau {
  INFO = 'INFO',
  WAARSCHUWING = 'WAARSCHUWING',
  FOUT = 'FOUT',
}

function log(niveau: LogNiveau, bericht: string): void {
  const tijdstip = Utilities.formatDate(new Date(), 'Europe/Amsterdam', 'yyyy-MM-dd HH:mm:ss');
  console.log(`[${tijdstip}] [${niveau}] ${bericht}`);
}

Conclusie

clasp met TypeScript blijft de professionele manier om Apps Script te bouwen: typeveiligheid, betere tooling en Git-versiecontrole. Het grote verschil sinds clasp 3 is dat je zelf een bundelstap toevoegt. Wie dat eenmaal heeft ingericht, ontwikkelt sneller en betrouwbaarder dan in de online-editor.