times-square-integration
Times Square notebook execution system integration patterns. Use this skill when working with Times Square pages, implementing SSE updates, handling URL parameters, setting up GitHub PR previews, or working with the Times Square API. Covers context providers, data fetching hooks, mock API endpoints, and page routing patterns.
When & Why to Use This Skill
The Times Square Integration skill provides a comprehensive set of architectural patterns and tools for embedding computational notebooks into web applications. It streamlines the implementation of real-time Server-Sent Events (SSE), URL-based state management, and GitHub PR previews, offering developers ready-to-use React context providers, data-fetching hooks, and mock API configurations for efficient development and testing.
Use Cases
- Real-time Execution Monitoring: Implementing Server-Sent Events (SSE) to display live updates and execution status of computational notebooks.
- Dynamic State Synchronization: Managing complex notebook parameters through URL-based state management using specialized React contexts.
- Automated PR Previews: Setting up workflows to preview notebook changes directly from GitHub Pull Requests, enhancing the code review process.
- Rapid Local Development: Utilizing mock API endpoints to simulate the Times Square backend, allowing frontend developers to build and test UI components without a live execution environment.
- Optimized Data Fetching: Leveraging custom SWR-based hooks to handle notebook metadata and HTML rendering with built-in caching and error handling.
| name | times-square-integration |
|---|---|
| description | Times Square notebook execution system integration patterns. Use this skill when working with Times Square pages, implementing SSE updates, handling URL parameters, setting up GitHub PR previews, or working with the Times Square API. Covers context providers, data fetching hooks, mock API endpoints, and page routing patterns. |
Times Square Integration
Times Square is a notebook execution system integrated into the squareone app for displaying computational notebooks.
Core Concepts
- Pages: Notebooks that can be executed and displayed
- Parameters: URL-based parameters for notebook execution
- SSE (Server-Sent Events): Real-time updates during execution
- GitHub PR Previews: Preview notebooks from pull requests
Context Providers
TimesSquareUrlParametersContext
Manages URL-based state for Times Square pages.
import { TimesSquareUrlParametersContext } from '../contexts/TimesSquareUrlParametersContext';
// Provider setup (usually in page)
<TimesSquareUrlParametersContext.Provider value={urlParams}>
<TimesSquarePage />
</TimesSquareUrlParametersContext.Provider>
// Usage in components
const { getParameter, setParameter } = useContext(TimesSquareUrlParametersContext);
const value = getParameter('myParam');
setParameter('myParam', 'newValue');
TimesSquareHtmlEventsContext
Manages real-time SSE (Server-Sent Events) updates.
import { TimesSquareHtmlEventsContext } from '../contexts/TimesSquareHtmlEventsContext';
// Provider setup
<TimesSquareHtmlEventsContext.Provider value={eventSource}>
<TimesSquarePage />
</TimesSquareHtmlEventsContext.Provider>
// Usage
const events = useContext(TimesSquareHtmlEventsContext);
// events provides real-time updates from notebook execution
Data Fetching Hooks
useTimesSquarePage
Custom hook for fetching Times Square page data.
import { useTimesSquarePage } from '../hooks/useTimesSquarePage';
function MyComponent({ pageSlug }) {
const { data, error, isLoading } = useTimesSquarePage(pageSlug);
if (isLoading) return <div>Loading...</div>;
if (error) return <div>Error: {error.message}</div>;
return <div>{data.displayName}</div>;
}
Pattern uses SWR for caching and revalidation.
Routing Patterns
Regular Pages
/times-square/{page-slug}
GitHub PR Previews
/times-square/github-pr/{owner}/{repo}/{commit}
Example:
/times-square/github-pr/lsst-sqre/times-square-demo/abc123
API Routes
Mock API endpoints in development (/pages/api/dev/times-square/):
GET /times-square/api/v1/pages- List pagesGET /times-square/api/v1/pages/:page- Page metadataGET /times-square/api/v1/pages/:page/html- Rendered HTMLGET /times-square/api/v1/pages/:page/htmlstatus- Execution statusGET /times-square/api/v1/pages/:page/htmlevents- SSE endpoint
Mock API Endpoints
For local development without Times Square backend:
// pages/api/dev/times-square/v1/pages/[page]/html.ts
import type { NextApiRequest, NextApiResponse } from 'next';
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
const { page } = req.query;
// Return mock HTML
res.status(200).json({
html: '<div>Mock Times Square page</div>',
parameters: {},
});
}
Page Component Pattern
import { GetServerSideProps } from 'next';
import { useTimesSquarePage } from '../hooks/useTimesSquarePage';
import { TimesSquareUrlParametersContext } from '../contexts/TimesSquareUrlParametersContext';
import { loadAppConfig } from '../lib/config/loader';
type Props = {
pageSlug: string;
};
export default function TimesSquarePage({ pageSlug }: Props) {
const { data, error, isLoading } = useTimesSquarePage(pageSlug);
if (isLoading) return <div>Loading notebook...</div>;
if (error) return <div>Error loading notebook</div>;
return (
<div>
<h1>{data.displayName}</h1>
<div dangerouslySetInnerHTML={{ __html: data.html }} />
</div>
);
}
export const getServerSideProps: GetServerSideProps<Props> = async (context) => {
const appConfig = await loadAppConfig();
const pageSlug = context.params?.page as string;
return {
props: {
appConfig,
pageSlug,
},
};
};
SSE Integration
function TimesSquareLivePage({ pageSlug }) {
const [eventSource, setEventSource] = useState(null);
useEffect(() => {
const es = new EventSource(
`/times-square/api/v1/pages/${pageSlug}/htmlevents`
);
es.onmessage = (event) => {
const data = JSON.parse(event.data);
// Handle real-time updates
console.log('New data:', data);
};
setEventSource(es);
return () => es.close();
}, [pageSlug]);
return (
<TimesSquareHtmlEventsContext.Provider value={eventSource}>
{/* Page content */}
</TimesSquareHtmlEventsContext.Provider>
);
}
Configuration
Times Square URL configured in AppConfig:
# squareone.config.yaml
timesSquareUrl: 'http://localhost:3000/times-square/api' # Dev
# timesSquareUrl: 'https://data.lsst.cloud/times-square/api' # Prod
Access in components:
import { useAppConfig } from '../contexts/AppConfigContext';
const config = useAppConfig();
const timesSquareUrl = config.timesSquareUrl;
Best Practices
- Use context providers for shared state
- Cache with SWR for performance
- Mock APIs for development
- Handle loading states gracefully
- Clean up SSE connections on unmount
- Validate parameters before execution
- Show execution progress with SSE
- Handle errors appropriately