@mcpher/gas-fakes

v2.5.3

Published

a day ago

An implementation of the Google Workspace Apps Script runtime: Run native App Script Code on Node and Cloud Run

0High
0Medium
0Low

brucemcpherson

Run Native Apps Script code anywhere with gas-fakes

Google Apps Script, meet Local Development.

gas-fakes is a powerful emulation layer that lets you run Apps Script projects on Node.js as if they were native. By translating GAS service calls into granular Google API requests, it provides a secure, high-speed sandbox for local debugging and automated testing.

Built for the modern stack, it features plug-and-play containerization—allowing you to package your scripts as portable microservices or isolated workers. Coupled with automated identity management, gas-fakes handles the heavy lifting of OAuth and credential cycling, enabling your scripts to act on behalf of users or service accounts without manual intervention. It’s the missing link for building robust, scalable Google Workspace automations and AI-driven workflows.

Getting started as a package user

You can get the package from npm:

npm i @mcpher/gas-fakes

For a complete guide on how to set up your local environment for authentication and development, please see the consolidated guide: Getting Started with gas-fakes

Collaborators should fork the repo and use the local versions of these files - see collaborators info.

Use exactly the same code as in Apps Script

Usage

Just as on Apps Script, everything is executed synchronously so you don't need to bother with handling Promises/async/await. Just write normal Apps Script code. Usually you would have an associated App Script project if that's your eventual target. Just like Apps Script, you need a manifest file (appsscript.json) so you can be sure that the correct scopes are authorized and asked for.

Local Web Development (`doGet` / `doPost`)

You can develop and test Google Apps Script Web Apps and UI Add-ons entirely on your local machine using the built-in local web server. The gas-fakes serve command spins up a local HTTP endpoint that routes requests to your doGet or doPost functions, perfectly emulating the Apps Script environment.

It features complete support for:

HtmlService templating (<?!= include() ?>).
Client-side RPC via google.script.run.
Visual UI emulation for Add-ons: Calling SpreadsheetApp.getUi().showSidebar(html) automatically frames your HTML output inside a visually accurate Workspace-style sidebar right in your browser!

See the Local Web Development Guide for full details.

Natural Language Automation with `@gf_agent`

With the introduction of the gf_agent skill for Gemini CLI and the built-in MCP server, you can now automate Google Workspace tasks using natural language. This specialized agent understands the full range of gas-fakes services and can generate and execute code locally based on your plain English prompts. Whether it's summarizing emails in a Google Doc or analyzing spreadsheet data, you can now do it directly from your terminal using plain English. See the gf_agent documentation for more details.

Note on appsscript.json: For full fidelity with live Apps Script, you should have a manifest available. However, as a workaround for "pure" gas-fakes projects where there is no intention to run in live Apps Script, if appsscript.json is missing or has no scopes, the runtime will automatically emulate one using the DEFAULT_SCOPES and EXTRA_SCOPES defined in your .env file, and will default the script's timeZone to America/New_York (or GF_TIMEZONE).

gas-fakes-cli

Now you can run apps script code directly from your console - for example

gas-fakes  -s "const files=DriveApp.getRootFolder().searchFiles('title contains \"Untitled\"');while (files.hasNext()) {console.log(files.next().getName())};"

For details see gas fakes cli

Configuration

Configuration for your local Node environment is handled interactively by the gas-fakes init process, which manages the necessary environment variables in your .env file.

Note on Consumer Accounts and ADC

If you are using a consumer account (gmail.com) or do not have access to Domain-Wide Delegation (DWD), you must use Application Default Credentials (AUTH_TYPE="adc") to authenticate with Google Workspace assets.

Important Security Note: Due to recent Workspace security changes, you must create and provide a custom OAuth2 client credentials JSON file during initialization (gas-fakes init) to avoid 403 Access Blocked errors when using Workspace scopes (like Gmail or Drive).

Guide: How to allow access to Workspace scopes with Application Default Credentials
Link to Create Credentials: Google Cloud Console Credentials Page

Security Warning: Always add your client credentials JSON file to your .gitignore to prevent it from being committed to GitHub or other source control.

Cloud Logging Integration

gas-fakes emulates the native Google Apps Script Logger.log() integration with Google Cloud Logging, allowing you to send structured logs from your local Node.js environment directly to your Google Cloud project. Note that console.log is the normal Node console and writes to the local console only. All messages from gas-fakes api still go to the console, so the Logger.log is for your own user messages as required.

Initial Configuration

The initial logging behavior is controlled by the LOG_DESTINATION environment variable in your .env file.

| LOG_DESTINATION | Behavior | |---|---| | CONSOLE (Default) | Logs structured JSON to the console (stdout). This is the default behavior if the variable is not set. | | CLOUD | Sends logs directly to Google Cloud Logging. Nothing is written to the console. | | BOTH | Sends logs to both Google Cloud Logging and the console. | | NONE | Disables all output from Logger.log(). |

When logging to the cloud, entries are sent to the gas-fakes/console_logs log name and include the following labels for easy filtering in the Log Explorer:

gas-fakes-scriptId
gas-fakes-userId

Dynamic Control

You can change the logging destination at any time during runtime by setting the Logger.__logDestination property. This is especially useful for testing or for applications that need to change their logging behavior dynamically.

The method accepts one of the following string values: 'CONSOLE', 'CLOUD', 'BOTH', or 'NONE'.

Example Usage

To set the initial destination, modify your .env file:

LOG_DESTINATION="BOTH"

To change the destination during runtime in your script:

// Initially logs to BOTH (from .env)
Logger.log('This goes to console and cloud');

// Switch to only logging to the console
Logger.__logDestination='CONSOLE';
Logger.log('This now only goes to the console');

// Disable logging completely
Logger.__logDestination='NONE';
Logger.log('This goes nowhere');

Link to Cloud log for this run

If you have used Logging to cloud, you can get a link to the log data like this.

console.log ('....example cloud log link for this session',Logger.__cloudLogLink)

It contains a cloud logging query that will display any logging done in this session - the filter is based on the scriptId (from the environment), the projectId and userId (from Auth), as well as the start and end time of the session.

Finally, another approach is to set it dynamically at the beginning of your app.

Logger.__logDestination="BOTH"

Do whichever one suits you best.

Troubleshooting: Missing Environment Tags

If you see a warning or error like Project '...' lacks an 'environment' tag, it means your Google Cloud Organization has a policy requiring projects to be designated with an environment tag (e.g., Development, Production).

You can ignore this, but you can resolve it if you want to keep things tidy. You need to bind an environment tag to your project. Replace YOUR_ORG_ID and YOUR_PROJECT_ID with your actual identifiers:

# Bind the 'Development' environment tag to your project
gcloud resource-manager tags bindings create \
  --tag-value=YOUR_ORG_ID/environment/Development \
  --parent=//cloudresourcemanager.googleapis.com/projects/YOUR_PROJECT_ID

Note: The tag key environment and the value Development must already exist at the organization level. If they don't, you (or your admin) will need to create them first using gcloud resource-manager tags keys create and gcloud resource-manager tags values create.

Pushing files to GAS

There are a couple of syntactical differences between Node and Apps Script. Not in the body of the code but in how the IDE executes. The 2 main ones are

apps script doesnt support 'import'. Alls its top level variables are global, so we need to drop imports from the files that are pushed to the IDE
Script run on Node are called immediately. Normally on Apps Script we hit the run button. Here's how I handle this in my scripts that need to run on both environments.

// this required on Node but not on Apps Script
if (ScriptApp.isFake) testFakes()

For pushing modified files back to the Apps Script IDE, use the built-in gas-fakes togas CLI command which handles necessary module syntax transformations automatically.

Help

As I mentioned earlier, to take this further, I'm going to need a lot of help to extend the methods and services supported - so if you feel this would be useful to you, and would like to collaborate, please ping me on [email protected] and we'll talk.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme