Code Example Standards

This guide defines the standards for code examples across the Kernel documentation.

General Principles

Context-aware completeness: Full examples must run as-is. Focused snippets can rely on variables introduced by surrounding text or sibling examples, but they must make those dependencies obvious.
Consistent naming: Use standardized variable names across all examples
No real secrets: Never include real API keys, passwords, tokens, or live credentials. Use obviously fake values when an auth-flow example needs credential-shaped input.
Multi-language support: When applicable, show TypeScript/JavaScript, Python, and Go examples

Variable Naming Conventions

TypeScript/JavaScript

SDK client: kernel
Browser instance: kernelBrowser
Additional browsers: kernelBrowser2, kernelBrowserAuto, etc.
Playwright/Puppeteer browser: browser
Context: context
Page: page

Python

SDK client: kernel
Browser instance: kernel_browser
Additional browsers: kernel_browser2, etc.
Playwright browser: browser
Context: context
Page: page

Go

SDK client: client
Browser instance: kernelBrowser
Additional browsers: kernelBrowser2, etc.
Context: ctx
Session ID: sessionID
Invocation ID: invocationID

Code Example Structure

Full examples vs focused snippets

Use a full example when the reader needs to copy and run a standalone program. Include imports, SDK initialization, context setup, the main operation, and error handling. Use a focused snippet when the page is walking through one step in a larger flow. Keep the snippet small, but rely only on variables the page already introduced, such as client, ctx, kernelBrowser, auth, or browser.

Minimal Example (Browser Creation)

Always include:

Import statement
SDK initialization
The main operation
Return value or console output (when relevant)

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const kernelBrowser = await kernel.browsers.create();
console.log(kernelBrowser.session_id);

from kernel import Kernel

kernel = Kernel()

kernel_browser = kernel.browsers.create()
print(kernel_browser.session_id)

package main

import (
	"context"
	"fmt"

	"github.com/kernel/kernel-go-sdk"
)

func main() {
	ctx := context.Background()
	client := kernel.NewClient()

	kernelBrowser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{})
	if err != nil {
		panic(err)
	}

	fmt.Println(kernelBrowser.SessionID)
}

Full Example (With Browser Automation)

For examples showing browser automation, include:

All necessary imports
SDK initialization
Browser creation
CDP connection
Browser automation code
Error handling (try/finally)
Cleanup

import Kernel from '@onkernel/sdk';
import { chromium } from 'playwright';

const kernel = new Kernel();

const kernelBrowser = await kernel.browsers.create();
const browser = await chromium.connectOverCDP(kernelBrowser.cdp_ws_url);

try {
  const context = browser.contexts()[0] || (await browser.newContext());
  const page = context.pages()[0] || (await context.newPage());
  await page.goto('https://www.onkernel.com');
  const title = await page.title();
  console.log(title);
} catch (error) {
  console.error(error);
} finally {
  await browser.close();
  await kernel.browsers.deleteByID(kernelBrowser.session_id);
}

from kernel import Kernel
from playwright.async_api import async_playwright

kernel = Kernel()

kernel_browser = kernel.browsers.create()

async with async_playwright() as playwright:
    browser = await playwright.chromium.connect_over_cdp(kernel_browser.cdp_ws_url)
    context = browser.contexts[0] if browser.contexts else await browser.new_context()
    page = context.pages[0] if context.pages else await context.new_page()

    try:
        await page.goto('https://www.onkernel.com')
        title = await page.title()
        print(title)
    except Exception as e:
        print(e)
    finally:
        await browser.close()
        await kernel.browsers.delete_by_id(kernel_browser.session_id)

SDK Initialization

✅ Correct - No hardcoded credentials

const kernel = new Kernel();

kernel = Kernel()

package main

import "github.com/kernel/kernel-go-sdk"

func main() {
	_ = kernel.NewClient()
}

The SDK automatically reads the API key from the KERNEL_API_KEY environment variable.

❌ Incorrect - Hardcoded credentials

// DON'T DO THIS
const kernel = new Kernel({ apiKey: 'your-api-key' });
const kernel = new Kernel({ apiKey: process.env.KERNEL_API_KEY });

# DON'T DO THIS
kernel = Kernel(api_key="your-api-key")
kernel = Kernel(api_key=os.getenv("KERNEL_API_KEY"))

// DON'T DO THIS
package main

import (
	"github.com/kernel/kernel-go-sdk"
	"github.com/kernel/kernel-go-sdk/option"
)

func main() {
	_ = kernel.NewClient(
		option.WithAPIKey("your-api-key"),
	)
}

Feature-Specific Examples

Simple Feature Toggle

For simple feature flags (stealth, headless, etc.):

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const kernelBrowser = await kernel.browsers.create({
  stealth: true,
});

from kernel import Kernel

kernel = Kernel()

kernel_browser = kernel.browsers.create(
    stealth=True,
)

package main

import (
	"context"

	"github.com/kernel/kernel-go-sdk"
)

func main() {
	ctx := context.Background()
	client := kernel.NewClient()

	_, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
		Stealth: kernel.Bool(true),
	})
	if err != nil {
		panic(err)
	}
}

Feature with Configuration

For features requiring configuration objects:

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const kernelBrowser = await kernel.browsers.create({
  stealth: true
});

from kernel import Kernel

kernel = Kernel()

kernel_browser = kernel.browsers.create(
    stealth=True
)

package main

import (
	"context"

	"github.com/kernel/kernel-go-sdk"
)

func main() {
	ctx := context.Background()
	client := kernel.NewClient()

	kernelBrowser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
		Stealth: kernel.Bool(true),
	})
	if err != nil {
		panic(err)
	}

	_ = kernelBrowser
}

App Development Examples

Kernel app examples currently use TypeScript/JavaScript and Python. Add a Go version only after the Go SDK has documented app framework support and the snippet has been tested against that SDK. For Kernel app examples, follow this pattern:

import Kernel, { type KernelContext } from '@onkernel/sdk';
import { chromium } from 'playwright';

const kernel = new Kernel();
const app = kernel.app('my-app-name');

app.action('action-name', async (ctx: KernelContext, payload) => {
  const kernelBrowser = await kernel.browsers.create({
    invocation_id: ctx.invocation_id,
  });

  const browser = await chromium.connectOverCDP(kernelBrowser.cdp_ws_url);
  const context = browser.contexts()[0] || (await browser.newContext());
  const page = context.pages()[0] || (await context.newPage());

  try {
    // Your action logic here
    return { result: 'success' };
  } finally {
    await browser.close();
  }
});

from kernel import Kernel, KernelContext
from playwright.async_api import async_playwright

kernel = Kernel()
app = kernel.App("my-app-name")

@app.action("action-name")
async def action_method(ctx: KernelContext, payload):
    kernel_browser = kernel.browsers.create(invocation_id=ctx.invocation_id)

    async with async_playwright() as playwright:
        browser = await playwright.chromium.connect_over_cdp(kernel_browser.cdp_ws_url)
        context = browser.contexts[0] if browser.contexts else await browser.new_context()
        page = context.pages[0] if context.pages else await context.new_page()

        try:
            # Your action logic here
            return {"result": "success"}
        finally:
            await browser.close()

Common Patterns

Pattern: Context and Page Access

Kernel browsers launch with a default context and page. Always use this pattern:

const context = browser.contexts()[0] || (await browser.newContext());
const page = context.pages()[0] || (await context.newPage());

context = browser.contexts[0] if browser.contexts else await browser.new_context()
page = context.pages[0] if context.pages else await context.new_page()

Pattern: Error Handling

Always include proper error handling:

try {
  // Your automation code
} catch (error) {
  console.error(error);
} finally {
  await browser.close();
  await kernel.browsers.deleteByID(kernelBrowser.session_id);
}

try:
    # Your automation code
except Exception as e:
    print(e)
finally:
    await browser.close()
    await kernel.browsers.delete_by_id(kernel_browser.session_id)

Code Formatting

Indentation

TypeScript/JavaScript: 2 spaces
Python: 4 spaces
Go: tabs from gofmt

String Quotes

TypeScript/JavaScript: Single quotes ' (except for avoiding escaping)
Python: Double quotes "
Go: Double quotes "

Line Length

Keep lines under 100 characters when possible
Break long parameter lists across multiple lines

Comments

Use comments sparingly; keep code self-explanatory
Add comments only for non-obvious logic or important context
Never add comments like “NEW CODE:” or similar meta-comments

URL and Placeholder Formatting

URLs with Placeholders

Use angle brackets for placeholders:

https://api.onkernel.com/browser/live/<TOKEN>?readOnly=true

IDs in Code

Use descriptive strings:

await kernel.browsers.deleteByID('session_id');

Multi-Language CodeGroups

Always use <CodeGroup> with proper language labels:

<CodeGroup>
```typescript Typescript/Javascript
// TypeScript code here
```

```python Python
# Python code here
```

```go Go
// Go code here
```
</CodeGroup>

Checklist

Before publishing a code example, verify:

Reference

See these files for examples:

introduction/create.mdx - Standard browser creation pattern
apps/develop.mdx - App development pattern
browsers/file-io.mdx - Complex automation example

Overview

Start building

How it works

Partnering with KERNEL

Code example guide

Code Example Standards

General Principles

Variable Naming Conventions

TypeScript/JavaScript

Python

Go

Code Example Structure

Full examples vs focused snippets

Minimal Example (Browser Creation)

Full Example (With Browser Automation)

SDK Initialization

✅ Correct - No hardcoded credentials

❌ Incorrect - Hardcoded credentials

Feature-Specific Examples

Simple Feature Toggle

Feature with Configuration

App Development Examples

Common Patterns

Pattern: Context and Page Access

Pattern: Error Handling

Code Formatting

Indentation

String Quotes

Line Length

Comments

URL and Placeholder Formatting

URLs with Placeholders

IDs in Code

Multi-Language CodeGroups

Checklist

Reference

​Code Example Standards

​General Principles

​Variable Naming Conventions

​TypeScript/JavaScript

​Python

​Go

​Code Example Structure

​Full examples vs focused snippets

​Minimal Example (Browser Creation)

​Full Example (With Browser Automation)

​SDK Initialization

​✅ Correct - No hardcoded credentials

​❌ Incorrect - Hardcoded credentials

​Feature-Specific Examples

​Simple Feature Toggle

​Feature with Configuration

​App Development Examples

​Common Patterns

​Pattern: Context and Page Access

​Pattern: Error Handling

​Code Formatting

​Indentation

​String Quotes

​Line Length

​Comments

​URL and Placeholder Formatting

​URLs with Placeholders

​IDs in Code

​Multi-Language CodeGroups

​Checklist

​Reference

Code Example Standards

General Principles

Variable Naming Conventions

TypeScript/JavaScript

Python

Go

Code Example Structure

Full examples vs focused snippets

Minimal Example (Browser Creation)

Full Example (With Browser Automation)

SDK Initialization

✅ Correct - No hardcoded credentials

❌ Incorrect - Hardcoded credentials

Feature-Specific Examples

Simple Feature Toggle

Feature with Configuration

App Development Examples

Common Patterns

Pattern: Context and Page Access

Pattern: Error Handling

Code Formatting

Indentation

String Quotes

Line Length

Comments

URL and Placeholder Formatting

URLs with Placeholders

IDs in Code

Multi-Language CodeGroups

Checklist

Reference