Your First Script

In this tutorial, you will create a global script from scratch, register it in extensions_registry.json, and publish it to your community. By the end, you will have a script that runs on every page and logs a message to the browser console.

Before You Start

• You have a GitHub account.
• You have access to Sources in your platform (Integrations → Developer Studio → Sources).
• You have a connected GitHub organization — see Connect Your GitHub Account if you haven't connected one yet.
• You have the Developer Studio CLI installed — see Get Started with the CLI.
• You have a project created with gsds init, pushed to GitHub, and enabled in Sources with main as the watched branch — see Repository Layout and Repository & Branch Settings.

Step 1: Scaffold the Script

From the root of your project, run:

gsds script new hello

gsds script new creates scripts/hello/script.js and adds an entry for it to extensions_registry.json. Open scripts/hello/script.js and replace its content with:

import { web } from "@gainsight-hub/sdk";

try {
  const user = await web.Context.User();
  console.info("[gsds script] loaded for", user.username);
} catch (error) {
  console.warn("[gsds script] Web SDK unavailable:", error);
}

This is an ES module that imports the Web SDK from @gainsight-hub/sdk (see SDK). Global scripts run directly in the page context, so the page's own globals and DOM are available too. gsds script new (gsds 1.9.0+) registers the script with "attributes": {"type": "module"}, which a script that uses the import needs; --attr cannot change the type.

Step 2: Review the Registry Entry

Open extensions_registry.json at the root of your project. gsds script new added this entry to the scripts array. Add a description so the entry looks like this:

{
  "scripts": [
    {
      "name": "hello",
      "path": "scripts/hello/script.js",
      "description": "Logs the current user to the console on every page",
      "placement": "head",
      "attributes": {
        "type": "module"
      }
    }
  ]
}

The name field is the script's unique identifier within the scripts array. The path points to the script file, relative to the repository root. placement tells the platform where to inject the <script> tag — head is the default gsds script new uses. Module scripts are deferred, so the script runs after the page HTML is parsed.

Step 3: Push and Publish

Run gsds build to validate the registry, then commit and push your changes:

gsds build
git add extensions_registry.json scripts/hello/script.js
git commit -m "Add hello script"
git push

Go back to Integrations → Developer Studio → Sources and watch the build status for your repository. After a few seconds it will change to Completed.

If the status shows Failed, open the build details to see the error message. The most common cause at this stage is a JSON syntax error in extensions_registry.json.

Step 4: Verify It Runs

1. Open any page in your community.
2. Open the browser developer tools (F12 or right-click → Inspect).
3. Switch to the Console tab.

You should see [gsds script] loaded for followed by your username (or guest when signed out) logged to the console. Navigate between pages — the message is logged on each one, because the script is injected into every page by default.

If you do not see the log, check that the build completed successfully and that the page is from the community where your repository is enabled.

Step 5: Load the Script Only on Specific Pages

A script with no rules runs everywhere. To restrict it, add a rules array. Update your script entry so it only loads on the homepage:

{
  "scripts": [
    {
      "name": "hello",
      "path": "scripts/hello/script.js",
      "description": "Logs the current user to the console on the homepage",
      "placement": "head",
      "attributes": {
        "type": "module"
      },
      "rules": [
        { "field": "page", "operator": "eq", "value": "homepage" }
      ]
    }
  ]
}

Commit, push, and wait for the build to complete. Reload your community's homepage — you should still see the console message. Navigate to any other page — the message is gone.

For the full list of targeting fields and operators, see Page Targeting.

What You Built

You scaffolded a script with the CLI, registered it in the platform, pushed it to production, and verified it runs on community pages. You then added a rule to target a specific page. The script runs directly in the page context and reads the current user through the Web SDK import, on every page load that matches its rules.

What's Next

• Scripts Overview — mental model for how scripts are injected
• Script Definition Reference — every field and HTML attribute
• Page Targeting — all context fields and operators for conditional loading
• Your First Stylesheet — add global CSS using the same registry pattern