GMB Liquid Lib

A Google Apps Script library for replacing liquid-style variables ({{variableName}}) in Google Drive file names and file contents (Google Docs and Sheets). Includes full autocomplete and type-checking support — both in the GAS web editor and during local development with clasp.

What it does

The library scans a Google Drive folder (recursively) for files containing {{...}} placeholders and replaces them with provided values:

• File and folder names — renamed via the Drive API batch endpoint
• Google Docs content — replaced using the Docs API batchUpdate
• Google Sheets content — replaced using the Sheets API findReplace

Project structure

├── src/
│   ├── index.ts               # Library source code (exported public functions)
│   └── appsscript.json        # GAS manifest (copied to dist/ during build)
├── scripts/
│   └── generate-gas-stubs.js  # Generates dist/_stubs.js for GAS editor intellisense
├── dist/                      # Generated by build (git-ignored)
│   ├── _stubs.js              # Empty function declarations (for the GAS editor)
│   ├── bundle.js              # Bundled implementation
│   ├── appsscript.json        # Copied from src/
│   └── types/                 # TypeScript declarations (for the npm package)
├── .clasp.json                # Clasp configuration (git-ignored)
├── .clasp.json.example        # Clasp configuration template (tracked in git)
├── .claspignore               # Excludes types/ and *.js.map from push
├── rollup.config.js           # Bundles src/ → dist/bundle.js
├── tsconfig.json              # TypeScript configuration (IDE + type-checking)
└── tsconfig.declarations.json # Generates .d.ts files into dist/types/

Getting started

1. Set up the GAS script

Create a new script at script.google.com and copy the Script ID from the URL (/projects/<SCRIPT_ID>/edit). Copy the example file and replace YOUR_SCRIPT_ID_HERE with your Script ID:

cp .clasp.json.example .clasp.json

2. Install dependencies and build

npm install
npm run build

3. Push to GAS

npm run push

4. Add the library to a consumer project

In the consumer project's appsscript.json, add the library under dependencies.libraries. Set version to 0 to always use the latest unpublished version (developmentMode: true), or a specific version number for production.

{
  "dependencies": {
    "libraries": [
      {
        "userSymbol": "GmbLiquidLib",
        "scriptId": "YOUR_LIBRARY_SCRIPT_ID",
        "version": "0",
        "developmentMode": true
      }
    ]
  }
}

userSymbol is the namespace used in consumer code (e.g. GmbLiquidLib.replaceLiquids(...)).

API

getAllVariableNamesFromFolder(folderId)

Scans a Google Drive folder recursively and returns all files and folders that contain liquid variables, grouped by type.

const { filesWithVariablesInName, filesWithVariablesInside, foldersWithVariablesInName } =
  GmbLiquidLib.getAllVariableNamesFromFolder('FOLDER_ID');

replaceLiquids(filesWithVariablesInName, filesWithVariablesInside, foldersWithVariablesInName, variables)

Replaces liquid variables in file names and file contents using the provided key-value map.

GmbLiquidLib.replaceLiquids(
  filesWithVariablesInName,
  filesWithVariablesInside,
  foldersWithVariablesInName,
  {
    '{{firstName}}': 'Anna',
    '{{lastName}}':  'Svensson',
    '{{date}}':      '2026-02-16',
  }
);

Commands

| Command | Description | |---|---| | npm run build | Bundle, generate types and stubs | | npm run push | Build and push to GAS via clasp | | npm run typecheck | Run type-checking without building |