Skip to content

Installation Guide

Get gaslamp up and running in your Google Apps Script project in just a few steps.

Script Library Installation

Step 1: Get the Script ID

Text Only
1l2aZO5RkhmDHUwtR3gnrqDIWw84K_T-NBdLP7-X0-BjcA06YU0nbgCNQ

Step 2: Add to Your Project

  1. Open your Google Apps Script project

  2. Add the Library

    • Click on "Libraries" in the left sidebar (+ icon)
    • Paste the Script ID: 1l2aZO5RkhmDHUwtR3gnrqDIWw84K_T-NBdLP7-X0-BjcA06YU0nbgCNQ
    • Click "Look up"

  3. Configure the Library

    • Version: Select HEAD (latest) or a specific version number
    • Identifier: Enter gaslamp (this is how you'll reference it in code)
    • Click "Save"

Step 3: Verify Installation

Create a new function in your code.gs file and run it:

JavaScript
function testInstallation() {
  // Define a validation schema
  const schema = {
    name:  gaslamp.FlameGuards.isString,
    value: gaslamp.FlameGuards.isNumber,
  };

  // Create a BareFrame and validate with FlameFrame
  const df = gaslamp.BareFrame.fromArrays([['name', 'value'], ['Test', 42]]);
  const { passed, failed } = gaslamp.FlameFrame.from(df, schema);

  if (failed.length > 0) {
    console.error('Validation errors:', failed.display());
  } else {
    console.log('FlameFrame created:', passed.display());
    console.log('Installation successful!');
  }
}

If you see Installation successful! in the log, you're ready to go!

Version Selection

  • Pros: Always up-to-date with latest features and fixes
  • Cons: May have breaking changes
  • Use when: Learning, prototyping, staying current
  • Pros: Stable, predictable behavior
  • Cons: Manual updates required
  • Use when: Production apps, team projects

Tip: Start with HEAD for learning, then pin to a specific version for production.

Troubleshooting Installation

"Script not found" error

  • Problem: Invalid Script ID
  • Solution: Double-check the Script ID is copied correctly

"gaslamp is not defined" error

  • Problem: Library not properly loaded
  • Solution:
    1. Check the identifier is set to gaslamp
    2. Save the library configuration
    3. Refresh your script editor

Permission errors

  • Problem: Library requires additional permissions
  • Solution: Run a test function and authorize when prompted

"Cannot read property" errors

  • Problem: Calling methods that don't exist (often from outdated documentation)
  • Solution:
    1. Check the API Reference to verify the method exists
    2. If upgrading from v0.64.0 or earlier, see Upgrade to v0.65.0 for API changes ({frame, errors} → {passed, failed})

What's Included?

After installation, you'll have access to:

JavaScript
// Plain DataFrame
const df = gaslamp.BareFrame.fromArrays(data);

// Type-validated DataFrame (recommended)
const { passed, failed } = gaslamp.FlameFrame.from(df, schema);

// Type guards for schema definitions
const { FlameGuards, FlameWright } = gaslamp;

// Logging
const logger = new gaslamp.AfterGlow('MyApp');

// Time tracking
const smith = new gaslamp.ClockSmith();

Next Steps

Installation complete! Now you can:

  1. Take your first steps with a 5-minute tutorial
  2. Browse Modules to learn individual features
  3. Try Cookbooks for practical examples

Development Tips

  • Use .display(): Preview DataFrames in logs with frame.display() for full table output
  • Validate early: Call FlameFrame.from() right after reading data to catch issues quickly
  • Reuse schemas: Define schemas once and reuse them for consistency
  • Check quotas: Be aware of Google Apps Script quotas and limitations — large sheet operations may hit execution time limits
  • Use LazyFrame: For complex chains of operations, consider LazyFrame for deferred evaluation

Ready for your first FlameFrame? Head to First Steps!