@crimson-education/replit-sdk

Replit SDK for Crimson App

This SDK facilitates the rapid integration of Replit-hosted applications into the Crimson ecosystem.

Core Principle

The integration works by passing environment variables and user parameters via URL parameters (query string or hash) to the Replit frontend. This data is stored in-memory and persists until the current session ends, providing a seamless iframe integration experience.

Project Structure

• api:
  • bindApi(app): Binds /api/function routes to an Express app for forwarding GraphQL requests.
  • graphqlProxySchema: Zod schema for the proxy request body.
• components:
  • ExternalLink: A specialized component designed to handle navigation to external URLs (out of iframe).
• hooks:
  • useUrlParams(): Extracts and stores essential data (Auth Tokens, API endpoints) from the URL.
  • getStoredParam(key) / setStoredParams(values): Utilities for managing persisted parameters.
• functions:
  • Implementations for fundamental Crimson API calls like fetchLoginUser and fetchMyStudents.
• utils:
  • initDatadog(config): Manages Datadog initialization.
  • trackEvent(name): Analytics utility.
  • apiRequest(query, variables): A pre-configured GraphQL request client wrapper.

Quick Integration Guide

To integrate your Replit app into the Crimson ecosystem, follow these steps:

1. Install the SDK

npm install @crimson-education/replit-sdk@1.0.2-beta-16

2. Wrap your App with DevProvider

Initialize the context at the top level of your application.

import { IDevProvider } from '@crimson-education/replit-sdk/lib/context/dev-context';

function App() {
  return (
    <IDevProvider>
      <YourAppRoutes />
    </IDevProvider>
  );
}

3. Setup Express Proxy

In your server-side code (e.g., server/routes.ts), bind the API proxy:

import { bindApi } from '@crimson-education/replit-sdk';

export function registerRoutes(app: Express) {
  bindApi(app);
  // ... other routes
}

4. Use URL Parameters Hook

In your main component, use the hook to sync URL parameters to memory:

import { useUrlParams } from '@crimson-education/replit-sdk/lib/hooks/use-url-params';

function MainComponent() {
  useUrlParams();
  return <div>My Content</div>;
}

5. Handle External Links

Use the ExternalLink component for any links that should open outside the iframe:

import { ExternalLink } from '@crimson-education/replit-sdk';

<ExternalLink href="https://app.crimsoneducation.org">Go to Crimson App</ExternalLink>;

6. Initialize Analytics (Optional)

import { init as datadogInit, trackEvent } from '@crimson-education/replit-sdk';

datadogInit({ app: 'your-replit-app-name' });
trackEvent({ action: 'APP_LAUNCHED' });

7. Fetch Crimson Data

Use the built-in functions to fetch user or student data:

import { fetchLoginUser, fetchMyStudents } from '@crimson-education/replit-sdk/lib/functions';

const user = await fetchLoginUser();
// you may get multiple roles, just keep one of 'STRATEGIST', 'CASE_MANAGER', 'TUTOR',
const students = await fetchMyStudents(user.userId, ['STRATEGIST']);