@mcpher/gas-fakes

v2.2.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

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 authroized and asked for.

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 via environment variables, typically stored in a .env file and managed by the gas-fakes init process.

| Environment Variable | Default | Description | |---|---|---| | GF_MANIFEST_PATH | ./appsscript.json | Path to the appsscript.json manifest file. | | GF_CLASP_PATH | ./.clasp.json | Path to the .clasp.json file. | | GF_SCRIPT_ID | from clasp, or random | Discovered from .clasp.json or generated as a random UUID during gas-fakes init. Used for ScriptApp.getScriptId() and partitioning stores. | | GF_DOCUMENT_ID | null | A bound document ID for testing container-bound scripts. | | GF_CACHE_PATH | /tmp/gas-fakes/cache | Path for CacheService local file emulation. | | GF_PROPERTIES_PATH | /tmp/gas-fakes/properties | Path for PropertiesService local file emulation. | | GF_PLATFORM_AUTH | google | Comma-separated list of backends to initialize (google, ksuite, msgraph). | | AUTH_TYPE | dwd | Google auth type: dwd (Domain-Wide Delegation) or adc (Application Default Credentials). | | LOG_DESTINATION | CONSOLE | Logging destination: CONSOLE, CLOUD, BOTH, or NONE. | | STORE_TYPE | FILE | Internal storage type for properties/cache: FILE (local) or UPSTASH (Redis). |

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.

A note on .env location

You will have used the gas-fakes init command to create a .env file, containing the LOG_DESTINATION setting. You can change any of the settings in the .env file manually if you want to.

If you want to set an initial LOG_DESTINATION using that .env file, you have to let gas-fakes know where to find it. Let's assume it's in the same folder as your main script.

node yourapp.js
# or if your .env is somewhere else
node --env-file pathtoenv yourapp.js

Alternatively, instead of putting it in an env file, you can export it in your shell environment.

export LOG_DESTINATION="BOTH"

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 inspiration on pushing modified files to the IDE, see the togas.sh bash script I use for the test suite. There's also a complete push pull workflow available - see - push test pull

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.