Category: Advanced

As Google Apps Script developers, we live in a world of incredible convenience. Services like DriveApp, SpreadsheetApp, and GmailApp are powerful, intuitive, and deeply integrated into Google Workspace. They allow us to build solutions with remarkable speed.

But this convenience comes with a trade-off: our code becomes tightly coupled to the Apps Script runtime. When you write DriveApp.getFiles(), you’re writing code that can only ever run inside Apps Script.

What happens when you hit a wall? Your script might need more than the 30-minute execution limit, require more memory than the shared environment provides, or need to handle a level of concurrency that Apps Script isn’t designed for. In these moments, you need an “eject button”—a way to lift your code out of Apps Script and into a more scalable environment like Google Cloud Run, without starting from scratch.

This article is a guide to a professional workflow that makes this possible. It’s about writing portable Apps Script code from day one, so you’re always ready for the cloud.

The Portability Problem: Built-in Services vs. Raw APIs

The core of the issue lies in how we interact with Google’s services.

• Built-in Services (DriveApp, etc.): These are high-level abstractions. They provide incredibly useful helper functions (like getBlob()) that handle complex operations behind the scenes. However, they are a “black box” and exist only in Apps Script. For a fascinating look at the work involved in unpacking what these services do, check out Bruce Mcpherson’s gas-fakes project, which emulates these services for local testing.
• Direct API Calls: The alternative is to interact directly with the underlying Google Drive API (or Sheets API, etc.). This gives you granular control but requires you to handle raw HTTP requests with UrlFetchApp, manage authentication tokens, and implement your own error handling like exponential backoff.

Let’s be clear: this isn’t a call to abandon the built-in services. Far from it. The built-in services are indispensable for anything that interacts directly with the user’s live session. Examples include creating custom menus, displaying dialogs with HtmlService, acting on an onEdit(e) event object, or manipulating the user’s cursor position. For these tasks, the built-in services are not just the best choice; they are often the only choice. The “portable philosophy” is about being strategic. It’s about identifying the core, data-processing engine of your script—the part you suspect might one day need more power or time—and deliberately building that piece for portability.

Writing portable code means finding a middle ground: the convenience of a high-level interface with the cross-platform nature of direct API calls.

The Solution: An Abstraction Layer with Client Libraries

The secret to portability is to abstract away the platform-specific parts of your code. Instead of using the built-in services, you can use client libraries that work in both Apps Script and a standard Node.js environment.

1. In Apps Script: You can use the Google API Client Library Generator for Apps Script libraries. This repository includes over 400 Apps Script client libraries for Google APIs that provide a familiar, object-oriented interface (e.g., drive.files.list()) but handle the UrlFetchApp and token logic for you.
2. In Node.js (for Cloud Run): You use the official Google API Node.js Client Libraries (e.g., googleapis). These libraries are the industry standard and provide the exact same structural interface (e.g., drive.files.list()).

A Real-World Example: Bulk PDF Generation

Let’s imagine a common business need: a script that takes data from a Google Sheet to generate hundreds of personalized offer letters as PDFs from a Google Doc template. Doing this one-by-one in Apps Script would be slow and might time out. This is a perfect candidate for the “eject button.”

Here is how we can write a single, portable function for the core logic.

The Portable Core Logic

This function contains the business logic. It’s agnostic to its environment; it only needs an initialized driveClient and docsClient to do its work. To ‘see’ what this looks like view this Apps Script project which has already had the Drive and Docs client libraries from the client library generator build directory.

/**
 * PORTABLE CORE LOGIC
 * This function is almost perfectly portable between Apps Script and Node.js.
 * @param {object} job The job details (templateId, replacements, etc.).
 * @param {object} driveClient An initialized Drive API client.
 * @param {object} docsClient An initialized Docs API client.
 * @param {object} logger A logger object (like `console`).
 */
async function _portablePdfGeneratorLogic(job, driveClient, docsClient, logger) {
  const { templateId, destinationFolderId, replacements, newFileName } = job;
  let newFileId = null;

  try {
    // 1. Copy the template document
    logger.log(`Copying template: ${templateId}`);
    // NOTE for Node.js: The response is often nested, e.g., `response.data.id`
    const copyResponse = await driveClient.files.copy({
      fileId: templateId,
      requestBody: { name: newFileName },
    });
    newFileId = copyResponse.id || copyResponse.data.id;

    // 2. Perform the text replacements in the new document
    logger.log(`Replacing text in new file: ${newFileId}`);
    await docsClient.documents.batchUpdate({
      documentId: newFileId,
      requestBody: { requests: replacements },
    });

    // 3. Export the document as a PDF
    logger.log(`Exporting file as PDF...`);
    // NOTE for Node.js: The response is a stream, not a blob.
    const pdfResponse = await driveClient.files.export({
      fileId: newFileId,
      mimeType: 'application/pdf',
    }, { responseType: 'stream' });

    // 4. Create the final PDF file in the destination folder
    logger.log(`Creating PDF file in folder: ${destinationFolderId}`);
    await driveClient.files.create({
      requestBody: {
        name: `${newFileName}.pdf`,
        parents: [destinationFolderId],
      },
      media: {
        mimeType: 'application/pdf',
        body: pdfResponse.body || pdfResponse.data, // Accommodate both runtimes
      },
      fields: 'id',
    });

    logger.log(`Successfully created PDF for ${newFileName}`);
    return { status: 'success' };

  } catch (error) {
    const errorMessage = error.response ? JSON.stringify(error.response.data) : error.message;
    logger.error(`[Core Logic] Failed: ${errorMessage}`);
    return { status: 'error', reason: errorMessage };
  } finally {
    // 5. Clean up the temporary Google Doc
    if (newFileId) {
      logger.log(`Cleaning up temporary file: ${newFileId}`);
      await driveClient.files.delete({ fileId: newFileId });
    }
  }
}

The Platform-Specific “Bootstrap” Code

The only part that needs to change is the code that initializes the clients and calls the core logic.

In Apps Script (Code.gs for testing and delegation):

/**
 * This function is for testing the portable logic *within* Apps Script.
 */
function runPdfJobInAppsScript(job) {
  // 1. Initialize the Apps Script community client libraries
  // These libraries automatically use the user's token via ScriptApp.getOAuthToken()
  const driveClient = new Drive(); // Assumes Drive.gs is in the project
  const docsClient = new Docs();   // Assumes Docs.gs is in the project

  // 2. Call the portable logic
  _portablePdfGeneratorLogic(job, driveClient, docsClient, Logger);
}
/**
 * This function delegates a job to a Cloud Run service, passing the user's
 * OAuth token to extend the "run as user" paradigm.
 */
function delegateJobToCloudRun(job) {
  const CLOUD_RUN_URL = 'https://your-service-url.a.run.app';
  
  const options = {
    method: 'post',
    contentType: 'application/json',
    // Get the user's OAuth token and pass it in the Authorization header.
    headers: {
      Authorization: 'Bearer ' + ScriptApp.getOAuthToken(),
    },
    payload: JSON.stringify(job),
    muteHttpExceptions: true,
  };
  
  const response = UrlFetchApp.fetch(CLOUD_RUN_URL, options);
  Logger.log(response.getContentText());
}

In Node.js (index.js for Cloud Run):

In our Node.js server, we’ll use the OAuth2Client from the google-auth-library. While many Cloud Run examples use GoogleAuth for service accounts, OAuth2Client is specifically designed to work with user-provided OAuth tokens, allowing us to seamlessly continue acting on behalf of the original user.

// Import OAuth2Client instead of GoogleAuth for this purpose
const { google } = require('googleapis');
const { OAuth2Client } = require('google-auth-library'); // 👈 Change this line
const express = require('express');

const app = express();
app.use(express.json());
const PORT = process.env.PORT || 8080;

// --- Main Express Route Handler ---
app.post('/', async (req, res) => {
  // 1. Extract the token from the Authorization header
  const authHeader = req.headers.authorization;
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).send('Unauthorized: Missing or invalid Authorization header.');
  }
  const userToken = authHeader.split(' ')[1];

  const { job } = req.body;
  if (!job) {
    return res.status(400).send('Invalid payload. Expected JSON with a "job" object.');
  }

  try {
    // 2. Create an OAuth2Client instance
    const auth = new OAuth2Client();

    // 3. Set the credentials using the token from Apps Script (or swap out for a service account config)
    auth.setCredentials({
      access_token: userToken,
    });

    // 4. Initialize the Google clients with the user-authed client
    const driveClient = google.drive({ version: 'v3', auth });
    const docsClient = google.docs({ version: 'v1', auth });

    // Now, any calls made with driveClient or docsClient will act on
    // behalf of the user who ran the Apps Script. 🚀
    const result = await _portablePdfGeneratorLogic(job, driveClient, docsClient, console);

    if (result.status === 'success') {
      res.status(200).send('PDF generated successfully.');
    } else {
      res.status(500).send(`Failed to generate PDF: ${result.reason}`);
    }
  } catch (err) {
    console.error(err);
    // Check for authentication errors specifically
    if (err.code === 401 || err.code === 403) {
      res.status(401).send('Authentication error with Google APIs. The token may be expired or invalid.');
    } else {
      res.status(500).send('An unexpected error occurred.');
    }
  }
});

app.listen(PORT, () => {
  console.log(`PDF generator service listening on port ${PORT}`);
  console.log('Ready to receive a test request...');
});

// (Paste the _portablePdfGeneratorLogic function here)
}

Conclusion: Start Portable, Scale with Confidence

The “eject button” is your strategic advantage, transforming Apps Script from just a scripting environment into the first stage of a professional development lifecycle. By separating your core logic from the convenient but platform-specific built-in services, you give your applications a future-proof foundation.

The key takeaway is simple: write your business logic for the Google APIs, not for the Apps Script runtime.

Your Next Step:The next time you start a project in Apps Script, challenge yourself to write just one core function in this portable style. You’ll not only prepare your code for future scaling but also gain a deeper understanding of the Google APIs themselves.