coze_studio/frontend/packages/arch/web-context

@coze-arch/web-context

Global Context for whole hot studio web app. You should keep using this package instead of call window.xxx directly

A centralized context management package that provides global state, event handling, and navigation utilities for Coze Studio web applications. This package helps you avoid direct window object manipulation and provides a structured way to handle global application state.

Features

• Global Variables Storage: Type-safe proxy-based global variable management
• Event Bus System: Centralized event handling with buffering capabilities
• Navigation Utilities: Safe URL redirection with future validation support
• Application Constants: Predefined enums for app sections and error codes
• Community Helpers: Specialized utilities for community bot store scenarios

Get Started

Installation

# Add to package.json
"@coze-arch/web-context": "workspace:*"

# Then run
rush update

Basic Usage

import {
  globalVars,
  GlobalEventBus,
  redirect,
  BaseEnum,
  SpaceAppEnum,
  COZE_TOKEN_INSUFFICIENT_ERROR_CODE
} from '@coze-arch/web-context';

// Use global variables
globalVars.LAST_EXECUTE_ID = 'some-execution-id';
console.log(globalVars.LAST_EXECUTE_ID);

// Create and use event bus
const eventBus = GlobalEventBus.create('myEventBus');
eventBus.on('dataChanged', (data) => {
  console.log('Data changed:', data);
});
eventBus.emit('dataChanged', { newValue: 'test' });

// Navigate safely
redirect('/new-page');

API Reference

Global Variables

globalVars

A proxy-based storage for global variables that provides type-safe access to shared state.

import { globalVars } from '@coze-arch/web-context';

// Set a global variable
globalVars.LAST_EXECUTE_ID = 'abc123';
globalVars.MY_CUSTOM_VAR = { key: 'value' };

// Get a global variable
const executeId = globalVars.LAST_EXECUTE_ID; // string
const customVar = globalVars.MY_CUSTOM_VAR; // unknown

// Undefined for unset variables
const unsetVar = globalVars.NONEXISTENT; // undefined

Features:

• Type-safe access through TypeScript interfaces
• Automatic storage in internal Map
• Returns undefined for unset properties
• Support for any serializable value type

Event Bus

GlobalEventBus.create<T>(key: string)

Creates or retrieves a singleton event bus instance for the given key.

import { GlobalEventBus } from '@coze-arch/web-context';

// Define event types
interface MyEvents {
  userLogin: [userId: string];
  dataUpdate: [data: { id: string; value: unknown }];
  error: [error: Error];
}

// Create event bus
const eventBus = GlobalEventBus.create<MyEvents>('app');

// Subscribe to events
eventBus.on('userLogin', (userId) => {
  console.log(`User ${userId} logged in`);
});

// Emit events
eventBus.emit('userLogin', 'user123');

// Unsubscribe
const handler = (data) => console.log(data);
eventBus.on('dataUpdate', handler);
eventBus.off('dataUpdate', handler);

Event Bus Control Methods

// Stop event processing (events will be buffered)
eventBus.stop();

// Events emitted while stopped are buffered
eventBus.emit('userLogin', 'user456'); // Buffered

// Start processing (flushes buffer)
eventBus.start(); // Now 'user456' login event fires

// Clear buffered events
eventBus.clear();

Key Features:

• Singleton pattern per key
• Event buffering when stopped
• Type-safe event definitions
• Standard EventEmitter3 API

Navigation

redirect(href: string)

Safely redirects to a new URL with potential for future validation logic.

import { redirect } from '@coze-arch/web-context';

// Redirect to external URL
redirect('https://example.com');

// Redirect to internal route
redirect('/dashboard');

// Redirect with query parameters
redirect('/search?q=test');

Constants

Application Enums

import { BaseEnum, SpaceAppEnum } from '@coze-arch/web-context';

// Base application sections
console.log(BaseEnum.Home);        // 'home'
console.log(BaseEnum.Store);       // 'store'
console.log(BaseEnum.Workspace);   // 'space'

// Space-specific applications
console.log(SpaceAppEnum.BOT);      // 'bot'
console.log(SpaceAppEnum.WORKFLOW); // 'workflow'
console.log(SpaceAppEnum.PLUGIN);   // 'plugin'

Error Codes

import { COZE_TOKEN_INSUFFICIENT_ERROR_CODE } from '@coze-arch/web-context';

// Check for token insufficient errors
const isTokenError = COZE_TOKEN_INSUFFICIENT_ERROR_CODE.includes(errorCode);
if (isTokenError) {
  // Handle token insufficient error - stop streaming
}

Community Constants

import {
  defaultConversationKey,
  defaultConversationUniqId
} from '@coze-arch/web-context';

// Use in community bot store scenarios
const conversationId = defaultConversationKey;     // -1
const uniqueId = defaultConversationUniqId;        // Unique string

Development

Project Structure

src/
├── const/           # Application constants
│   ├── app.ts      # Base and space app enums
│   ├── community.ts # Community-specific constants
│   └── custom.ts    # Error codes and custom constants
├── event-bus.ts     # Global event bus implementation
├── global-var.ts    # Global variables storage
├── location.ts      # Navigation utilities
└── index.ts         # Main exports

Running Tests

# Run tests
rush test --to @coze-arch/web-context

# Run tests with coverage
rush test:cov --to @coze-arch/web-context

Linting

# Lint the package
rush lint --to @coze-arch/web-context

Dependencies

Runtime Dependencies

• eventemitter3 (^5.0.1): High-performance event emitter for the event bus system
• lodash-es (^4.17.21): Utility functions (used for uniqueId generation)

Development Dependencies

• @coze-arch/eslint-config: Shared ESLint configuration
• @coze-arch/ts-config: Shared TypeScript configuration
• vitest: Testing framework with coverage support

Best Practices

1. Use typed event buses: Always define event interfaces for better type safety
2. Avoid direct window access: Use this package instead of direct window.xxx calls
3. Manage event subscriptions: Remember to unsubscribe from events to prevent memory leaks
4. Use singleton pattern: Create event buses with meaningful keys and reuse them
5. Handle buffered events: Consider using stop()/start() pattern for controlling event flow

License

Copyright © ByteDance Ltd. All rights reserved.