Getting Started

This project provides a React component containing the Raspberry Pi Code Editor for embedding inside other applications. Although originally bootstrapped with Create React App, the application has been ejected so all the build scripts etc. are now in the repo. Legacy web-component assets are still published for backwards compatibility, but the primary integration surface is the TextJamEditor React component.

Local development

The app test page at http://localhost:3011 can be used to develop the React component in isolation if needed.

Install dependencies

This repository uses Yarn 3 (see package.json → packageManager). Please install dependencies with Yarn:

yarn install

Using npm install can fail due to strict peer-dependency resolution in npm for some legacy packages in this project.

Available Scripts

In the project directory, you can run:

yarn start

Runs the app in the development mode.
Open http://localhost:3011 to view the web component test page in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

yarn test

Launches the test runner in interactive watch mode.
See the section about running tests for more information.

yarn build:lib

Builds the lib for production to the dist folder.
It bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

Styling

The dev playground (webpack.config.js) keeps styles in JavaScript via style-loader for the fastest live reload experience. The library build (webpack.lib.config.js) extracts all CSS/SCSS into dist/style.css using MiniCssExtractPlugin so consumers can import a single stylesheet while still benefitting from CSS Modules (*.module.(css|scss)) for scoped styles.

Styling Best Practices for Developers

Focus on CSS Modules: When adding or modifying styles, prioritize CSS Modules over global styles. Use the .module.css or .module.scss naming convention to ensure styles are scoped to components and avoid style conflicts.

Refactor Global Styles: When working on existing code, identify global styles and refactor them into CSS Modules when possible. This improves maintainability, reduces style conflicts, and makes components more self-contained.

CSS Modules Structure:

• Component-specific styles should live in ComponentName/styles.module.scss alongside the component
• Import styles as: import classes from './styles.module.scss'
• Use class names from the imported styles object: className={classes.container}
• Webpack automatically generates scoped class names like ComponentName__container--abc123

When Global Styles Are Acceptable:

• Design system tokens and variables (e.g., color palettes, spacing scales)
• Third-party library overrides that cannot be modularized
• Base resets or typography that must apply globally

Example - Preferred CSS Modules Approach:

// ComponentName/ComponentName.jsx
import classes from './styles.module.scss';

export function ComponentName() {
  return <div className={classes.container}>Content</div>;
}

// ComponentName/styles.module.scss
.container {
  padding: 1rem;
  background: var(--color-background);
}

Testing

Automated unit tests can be run via the yarn test command. These unit tests are written using the JavaScript testing framework Jest and make use of the tools provided by the React Testing Library. Automated accessibility testing for components is available via the jest-axe library. This can be achieved using the haveNoViolations matcher provided by jest-axe, although this does not guarantee that the tested components have no accessibility issues.

Publishing to npm

Prerequisites

1. Ensure you're logged into npm:

   npm login

2. Verify you have publish access to the gwchq-textjam package.

3. Make sure all changes are committed and the working directory is clean.

Publishing Steps

1. Update the version in package.json following semantic versioning:

   • Patch: 0.1.2 → 0.1.3 (bug fixes)
   • Minor: 0.1.2 → 0.2.0 (new features, backwards compatible)
   • Major: 0.1.2 → 1.0.0 (breaking changes)

2. Build the library (automatically runs via prepublishOnly hook):

   yarn build:lib

   This creates the dist folder with:

   • index.js - The main ESM module
   • style.css - Extracted stylesheet
   • assets/ - Static assets (icons, fonts, etc.)

3. Verify the build output:

   • Check that dist/index.js exists and is properly built
   • Verify dist/style.css contains all styles
   • Ensure all required assets are in dist/assets/

4. Publish to npm:

   npm publish

   The prepublishOnly script will automatically run yarn build:lib before publishing.

5. Verify publication:

   npm view gwchq-textjam version

What Gets Published

The following files are included in the npm package (as defined in package.json → files):

• dist/ - Built library files
• README.md - This file
• LICENSE - License file

Package Exports

Consumers can import:

• Main component: import { TextJamEditor } from "gwchq-textjam"
• Stylesheet: import "gwchq-textjam/style.css"

Using the editor as a React component

The editor can be imported and rendered directly inside another React application. The package exports the TextJamEditor component and styles.css:

import { TextJamEditor } from "gwchq-textjam";
import "gwchq-textjam/style.css"

export function EditorWrapper() {
  return (
    <TextJamEditor
      project={{ project_type: "python", identifier: "my-py-app" }}
    />
  );
}

The consumer's webpack config should include the following setups

{
  ...,
  modules: {
    rules: [
      ...,
      {
        test: /\.map$/,
        type: "asset/resource",
      },
      {
        test: /\.whl$/,
        type: "asset/resource",
      },
      {
        test: /\.glb$/,
        type: "asset/resource",
      },
    ]
  },
  plugins: [
    new CopyWebpackPlugin({
      patterns: [
        ...,
        {
          from: "node_modules/gwchq-textjam/dist/assets",
          to: "assets",
        },
      ],
    }),
  ],
  resolve: {
    extensions: ['.js', '.jsx'],
    alias: {
      'react': path.resolve(__dirname, 'node_modules/react'),
      'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),
      'react-redux': path.resolve(__dirname, 'node_modules/react-redux'),
    },
    fallback: {
      stream: require.resolve('stream-browserify'),
      path: require.resolve('path-browserify'),
      util: require.resolve('util/'),
      assert: require.resolve("assert"),
    },
  },
}

Component props

TextJamEditor accepts the following props (previously exposed as web-component attributes):

• project: an object with the project data. Contains the following props:
  • project_type: Possible values web | python. Default project files will be created according to this value
  • identifier: A string that represents the project id. If provided, cached project with same id will be loaded
  • packageApiUrl: A string with url to download pyodide packages. If not provided - default value is pyodide CDN.

// TODO: review old options below

• loadCache: Load latest version of project code from local storage (defaults to true)
• locale: Locale for UI elements and to determine the language of projects loaded from the API (defaults to en)
• outputOnly: Only display the output panel (defaults to false)
• outputPanels: Array of output panel names to display (defaults to ['text', 'visual'])
• outputSplitView: Start with split view in output panel (defaults to false, i.e. tabbed view)
• projectNameEditable: Allow the user to edit the project name in the project bar (defaults to false)
• readOnly: Display the editor in read-only mode (defaults to false)
• showSavePrompt: Prompt the user to save their work (defaults to false)
• sidebarOptions: Array of strings specifying the panels to be displayed in the sidebar. Options include "projects", "file", "download", "settings".

When no props are supplied the component falls back to parsing the current page’s query string so the local development experience (yarn start) continues to work unchanged. You can override this by explicitly passing queryString or the equivalent props.

Events and callbacks

For backwards compatibility the editor continues to dispatch the following document events. You can listen for them from your host application if you rely on the legacy integration layer:

• editor-codeChanged
• editor-navigateToProjectsPage
• editor-projectOwnerLoaded
• editor-runCompleted
• editor-runStarted
• editor-stepChanged
• editor-logIn
• editor-signUp
• editor-quizReady
• editor-themeUpdated

These events make it possible for the host page to react to code execution, project changes, authentication requests, and theme updates.