Basics
How HtmlService and google.script.run talk
Dialogs, sidebars, and web apps run HTML in the user browser while .gs code stays on Google servers. Only plain JSON-like values can cross between them.
1 of 4
Browser HTML and server .gs code never share memory
When a script opens a sidebar, modal dialog, or web app with HtmlService, the HTML, CSS, and <script> tags run inside the viewer browser inside a sandboxed iframe hosted under googleusercontent.com. Your .gs files stay on Google servers.
Every call to google.script.run starts a separate, fresh server execution. Top-level variables set during an earlier server call are gone by the time the user clicks the next button in the sidebar.
2 of 4
Which values can cross google.script.run
Because browser code and server code sit on opposite sides of an HTTPS boundary, google.script.run serializes arguments and return values. Only plain data survives the trip.
- Allowed: string, number, boolean, null, arrays of allowed values, and plain objects whose properties hold allowed values.
- Special client-only case: a single HTML <form> element may be passed as the sole argument from the browser to a server function, which receives its named inputs as an object.
- Blocked or corrupted: JavaScript Date instances! Returning a Date from a server function or passing one from the browser causes the call to fail or deliver null. Convert dates to ISO strings (date.toISOString()) or formatted text before returning them.
- Blocked: Apps Script service objects such as Range, Sheet, File, or GmailMessage, plus functions, Map, Set, RegExp, and raw File or Blob objects.
function getRecentRequestsForSidebar() {
const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
const sheet = spreadsheet.getSheetByName('Requests');
if (!sheet) throw new Error('Requests sheet is missing.');
const timeZone = spreadsheet.getSpreadsheetTimeZone();
const rows = sheet.getDataRange().getValues().slice(1, 11);
return rows.map(([id, requester, createdAt, status]) => ({
id: String(id),
requester: String(requester),
createdOn:
createdAt instanceof Date
? Utilities.formatDate(createdAt, timeZone, 'yyyy-MM-dd')
: String(createdAt),
status: String(status),
}));
} 3 of 4
Always attach both success and failure handlers
google.script.run is asynchronous in the browser: it returns void right away and runs your callback later. If a server function throws an Error and the browser page did not attach withFailureHandler(fn), the error disappears from the user interface and only appears in the browser console.
Chain withSuccessHandler and withFailureHandler before calling the server function name, and re-enable any disabled Submit button inside both callbacks so a failed check does not leave the form stuck.
4 of 4
Private server functions and sandboxed links
Any public function in your .gs files can be called from browser DevTools through google.script.run by someone who can open your dialog or web app. Put a trailing underscore on internal helpers (saveRecord_()) so google.script.run refuses to invoke them directly, and validate every input inside public server functions.
HtmlService always uses IFRAME sandbox mode; older NATIVE and EMULATED modes are retired. Inside that iframe, plain links (<a href="https://...">) cannot navigate the outer tab unless they include target="_blank" or target="_top" and the user clicks them.
Remember
The short version
- Each google.script.run call starts a fresh server execution with no memory from earlier button clicks.
- Never return a raw JavaScript Date or Apps Script Range across google.script.run; convert to strings, numbers, booleans, arrays, and plain objects.
- Always register both withSuccessHandler and withFailureHandler before calling the server function.
- End internal server helpers with an underscore so browser callers cannot invoke them through google.script.run.
Keep going
Put it to work
- Task guide Add a custom menu to a Google Sheet
Add a menu named Helpful tools to the menu bar of a Google Sheet. Its one item shows which cell is selected. Save the script, reload the Sheet, and the menu appears.
- Basics What works in the Apps Script V8 runtime
Apps Script runs modern V8 JavaScript on Google servers, without browser DOM globals, Node modules, or background timers.
- Basics Dates, time zones, and Utilities.formatDate
A Date holds one instant in time. Use Utilities.formatDate(date, timeZone, pattern) and Session.getScriptTimeZone() to format it in the right time zone.
- Basics Common Apps Script errors and what they mean
Apps Script error messages say what failed, for example TypeError: Cannot read properties of null (reading 'getRange') or ReferenceError. Find the exact message below for its cause and fix.