{"id":17235,"library":"gas-client","title":"Google Apps Script Client","description":"gas-client is a client-side utility library designed for Google Apps Script projects, providing a modern, promise-based interface for calling server-side Apps Script functions. It acts as a user-friendly wrapper around the native `google.script.run` API, abstracting away callback-based error and success handling in favor of standard JavaScript Promises and async/await syntax. The current stable version is 1.2.1, with minor releases and patches occurring as needed to address compatibility and improvements. A key differentiator is its ability to provide consistent access to `google.script.host` functions (like `close()` or `setHeight()`) in both production Apps Script environments and local development setups. It is specifically designed to integrate seamlessly with local development servers, such as those used in React Google Apps Script projects, by allowing explicit configuration of allowed development domains. This enables a more streamlined and conventional client-side development workflow for Apps Script.","status":"active","version":"1.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/enuchi/gas-client","tags":["javascript","Google","Apps","Script","GAS","Client","typescript"],"install":[{"cmd":"npm install gas-client","lang":"bash","label":"npm"},{"cmd":"yarn add gas-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add gas-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `GASClient` class is a named export. While the package publishes as UMD, it is primarily designed for ESM consumption. Using `require()` may require specific bundler configurations or lead to unexpected behavior.","wrong":"const GASClient = require('gas-client');","symbol":"GASClient","correct":"import { GASClient } from 'gas-client';"},{"note":"`serverFunctions` is an instance property obtained by destructuring a `GASClient` instance, not a direct module export. It provides promise-based wrappers for your server-side Apps Script functions.","wrong":"import { serverFunctions } from 'gas-client';","symbol":"serverFunctions","correct":"const { serverFunctions } = new GASClient();"},{"note":"`scriptHostFunctions` is also an instance property, similar to `serverFunctions`. It offers a consistent interface for `google.script.host` methods, functioning identically in both development and production environments.","wrong":"import { scriptHostFunctions } from 'gas-client';","symbol":"scriptHostFunctions","correct":"const { scriptHostFunctions } = new GASClient();"}],"quickstart":{"code":"import { GASClient } from 'gas-client';\n\n// Initialize GASClient, optionally for local development\nconst clientConfig = {\n  // In development mode, replace 3000 with your local dev server port\n  // This setting is ignored in production Apps Script environments.\n  allowedDevelopmentDomains: process.env.NODE_ENV === 'development' ? 'https://localhost:3000' : undefined,\n};\nconst { serverFunctions, scriptHostFunctions } = new GASClient(clientConfig);\n\n// Example 1: Calling a server function with Promises\nconst sheetTitle = 'MyNewSheet';\nserverFunctions.addSheet(sheetTitle)\n  .then((response) => {\n    console.log('Sheet added successfully:', response);\n    scriptHostFunctions.setHeight(500); // Example of using a host function\n  })\n  .catch((err) => {\n    console.error('Failed to add sheet:', err);\n  });\n\n// Example 2: Calling a server function with async/await\nasync function createAndLogSheet(title: string) {\n  try {\n    const response = await serverFunctions.addSheet(title);\n    console.log('Sheet created via async/await:', response);\n    scriptHostFunctions.focusEditor(); // Switch focus to the editor\n  } catch (err) {\n    console.error('Error in async/await:', err);\n  }\n}\n\n// Call the async function\ncreateAndLogSheet('AnotherSheet');","lang":"typescript","description":"Demonstrates how to initialize `GASClient`, call a server-side Apps Script function using promises or async/await, optionally configure it for local development, and utilize `scriptHostFunctions`."},"warnings":[{"fix":"Review your codebase for compatibility, especially if you had custom type declarations or relied on previous internal structures. Update client-side code to leverage the officially supported TypeScript types and new API patterns introduced in `v1.0.0`.","message":"The `v1.0.0` release introduced full TypeScript support and significant internal improvements, moving from a `v0.x` pre-release status to a stable major version. While specific breaking changes are not detailed, upgrading from `0.x` to `1.0.0` or higher may require code adjustments, particularly around type definitions and module resolution if you were using custom workarounds for types.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure that the `allowedDevelopmentDomains` property in your `GASClient` configuration exactly matches the full `https://localhost:PORT` URL of your local development server. This config is ignored in production.","message":"When developing locally, the `allowedDevelopmentDomains` configuration option is crucial. If omitted or incorrectly specified, client-side communication with your local development server (e.g., via `Google Apps Script Webpack Dev Server`) will fail, preventing server function calls.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Upgrade to `gas-client@1.2.1` or newer. This version includes optional chaining (`?.`) when accessing `google.script.host.editor`, mitigating the error in web app contexts.","message":"Prior to `v1.2.1`, attempts to use `scriptHostFunctions.focusEditor()` within a Google Apps Script web app (as opposed to dialogs or sidebars) could potentially lead to errors if `google.script.host.editor` was not fully available in that context, causing `gas-client` to fail loading.","severity":"gotcha","affected_versions":"<1.2.1"},{"fix":"Always use `.then((response) => {...}).catch((error) => {...})` or `try { const response = await serverFunctions.myFunction(); } catch (error) {...}` to ensure proper error handling and response processing.","message":"`gas-client` wraps the native `google.script.run` with Promises. Developers accustomed to `google.script.run.withSuccessHandler().withFailureHandler()` must transition to standard Promise handling (`.then().catch()`) or `async/await` (`try...catch`) for all server function calls made via `serverFunctions`.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `serverFunctions` is properly destructured from a `new GASClient()` instance: `const { serverFunctions } = new GASClient(config); serverFunctions.someServerFunction();`","cause":"Attempting to call a server function directly on the `GASClient` instance or without correctly destructuring `serverFunctions`.","error":"TypeError: Cannot read properties of undefined (reading 'someServerFunction')"},{"fix":"Set `allowedDevelopmentDomains` in your `GASClient` constructor options to the exact `https://localhost:PORT` URL of your running development server (e.g., `{ allowedDevelopmentDomains: 'https://localhost:3000' }`).","cause":"The `allowedDevelopmentDomains` configuration is either missing, incorrect, or doesn't match the actual URL of your local development server, preventing communication between the client and the mock server.","error":"Refused to connect to 'https://localhost:3000/' because it violates the following Content Security Policy directive..."},{"fix":"Always attach a `.catch()` handler to your promise chain (e.g., `serverFunctions.myFunc().then(...).catch(err => console.error(err))`) or wrap `await` calls in `try...catch` blocks (`try { await serverFunctions.myFunc(); } catch (err) { console.error(err); }`) to handle potential errors.","cause":"Server functions called via `serverFunctions` return Promises, and if an error occurs on the server-side Apps Script or during the call, the Promise will reject without being caught.","error":"Unhandled promise rejection"}],"ecosystem":"npm","meta_description":null}