Skip to content

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.
Convert Date cells to strings before returning rows to HtmlService
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.

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

All basics