> ## Documentation Index
> Fetch the complete documentation index at: https://calcs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub to Calcs Builder Workflow for Diagrams

> Step-by-step guide for developing, building, and deploying custom diagrams from GitHub repositories

Custom diagrams are developed in separate GitHub repositories, compiled locally, and then uploaded to the Calcs.com template builder. This workflow allows for sophisticated diagram development using modern web technologies.

## Overview

The workflow involves:

1. **Development**: Code diagrams in TypeScript/JavaScript
2. **Compilation**: Build diagrams into deployable assets
3. **Upload**: Deploy compiled files to template builder
4. **Integration**: Use diagrams in Calcs.com templates

## System Requirements

<Note>
  **Prerequisites (macOS):**

  * Homebrew package manager
  * Node.js and npm
  * Git
  * Code editor (VS Code recommended)

  For Windows users, the process may differ slightly.
</Note>

## First Time Setup

### 1. Install Development Tools

<CodeBlock title="Install Required Tools">
  ```bash theme={null}
  # Install Homebrew (if not already installed)
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  # Install npm via Homebrew
  brew install npm
  ```
</CodeBlock>

### 2. Clone Repository

<CodeBlock title="Clone Diagram Repository">
  ```bash theme={null}
  # Clone the specific diagram repository
  git clone https://github.com/ClearCalcs/[repository-name]

  # Navigate to repository
  cd [repository-name]

  # Pull latest changes
  git pull
  ```
</CodeBlock>

### 3. Navigate to Diagram Folder

<CodeBlock title="Navigate to Correct Folder">
  ```bash theme={null}
  # Navigate to the appropriate folder:
  cd /static      # For static diagrams
  # OR
  cd /interactive # For interactive diagrams

  # For repositories with multiple diagrams:
  cd solar/static              # Example: MAFI solar diagrams
  cd bracket-checker/static    # Example: MAFI bracket diagrams
  ```
</CodeBlock>

### 4. Install Dependencies

<CodeBlock title="Install Node Dependencies">
  ```bash theme={null}
  # Install required packages
  npm install
  ```
</CodeBlock>

<Note>
  You must run `npm install` in each diagram folder if the repository contains multiple diagrams.
</Note>

## Regular Development Workflow

### 1. Update Repository

<CodeBlock title="Update to Latest Version">
  ```bash theme={null}
  # Ensure you're in the correct repository
  pwd

  # Pull latest changes
  git pull
  ```
</CodeBlock>

### 2. Install Dependencies (if needed)

<CodeBlock title="Update Dependencies">
  ```bash theme={null}
  # Navigate to diagram folder
  cd /static  # or /interactive

  # Update packages
  npm install
  ```
</CodeBlock>

### 3. Compile Diagram

<CodeBlock title="Build Diagram">
  ```bash theme={null}
  # Compile the diagram
  npm run-script compile
  ```
</CodeBlock>

### 4. Locate Output Files

After compilation, you'll find the built files:

<Accordion title="Output File Locations">
  **For Static Diagrams:**

  * Location: `/dist/compiled.js`
  * File type: JavaScript module
  * Usage: Upload to template builder

  **For Interactive Diagrams:**

  * Location: `output/index.html`
  * File type: HTML with embedded JavaScript
  * Usage: Upload to template builder

  **If Both Types:**

  * Both files may need to be uploaded if modifications were made to each
</Accordion>

### 5. Upload to Template Builder

<CodeBlock title="Template Builder Upload">
  ```bash theme={null}
  # Files to upload:
  # - Static: dist/compiled.js
  # - Interactive: output/index.html

  # Upload process:
  # 1. Open Calcs.com template builder
  # 2. Navigate to diagram widget
  # 3. Upload the compiled file(s)
  # 4. Update calculator
  ```
</CodeBlock>

## Repository Structure Examples

### Single Diagram Repository

<CodeBlock title="Simple Repository Structure">
  ```
  diagram-repo/
  ├── src/
  │   ├── static/
  │   │   ├── render.ts
  │   │   └── package.json
  │   └── interactive/
  │       ├── interface.ts
  │       └── package.json
  ├── dist/
  └── output/
  ```
</CodeBlock>

### Multi-Diagram Repository

<CodeBlock title="Complex Repository Structure">
  ```
  mafi-diagrams/
  ├── solar/
  │   ├── static/
  │   │   ├── package.json
  │   │   └── src/
  │   └── interactive/
  │       ├── package.json
  │       └── src/
  ├── bracket-checker/
  │   ├── static/
  │   │   ├── package.json
  │   │   └── src/
  │   └── interactive/
  │       ├── package.json
  │       └── src/
  └── shared/
      └── components/
  ```
</CodeBlock>

## Development Best Practices

### Version Control

<CodeBlock title="Git Best Practices">
  ```bash theme={null}
  # Always start with latest code
  git pull

  # Create feature branches for major changes
  git checkout -b feature/new-diagram-type

  # Commit regularly with descriptive messages
  git commit -m "Add parameter validation for tube dimensions"

  # Push changes for review
  git push origin feature/new-diagram-type
  ```
</CodeBlock>

### Testing Workflow

1. **Local Testing**: Use `npm test` during development
2. **Integration Testing**: Upload to development template
3. **User Testing**: Test with real calculation scenarios
4. **Production Deployment**: Upload to live templates

### Dependency Management

<CodeBlock title="Managing Dependencies">
  ```bash theme={null}
  # Check for outdated packages
  npm outdated

  # Update specific package
  npm update [package-name]

  # Install new dependency
  npm install [package-name] --save
  ```
</CodeBlock>

## Troubleshooting

### Common Issues

<Accordion title="Compilation Errors">
  **Issue**: `npm run-script compile` fails

  **Solutions**:

  1. Ensure `npm install` was run successfully
  2. Check for TypeScript/JavaScript syntax errors
  3. Verify all required dependencies are installed
  4. Check Node.js version compatibility
</Accordion>

<Accordion title="Upload Issues">
  **Issue**: Compiled file doesn't work in template builder

  **Solutions**:

  1. Verify correct file was uploaded (compiled.js or index.html)
  2. Check file size limits
  3. Ensure diagram parameters match template expectations
  4. Test with minimal parameter set first
</Accordion>

### Debug Mode

<CodeBlock title="Enable Debug Mode">
  ```bash theme={null}
  # Run compilation with verbose output
  npm run-script compile --verbose

  # Check for detailed error messages
  npm run-script compile 2>&1 | tee compile.log
  ```
</CodeBlock>

## Video Tutorial

For a complete visual walkthrough of this workflow:

<Note>
  📹 **Watch the complete tutorial**: [GitHub to Calcs Builder Workflow](https://www.loom.com/share/ac16400594814901b5f0b713010507bc)

  This video covers the entire process from repository setup to template deployment.
</Note>

## Next Steps

After successfully compiling and uploading your diagram:

1. **Test Integration**: Verify the diagram works in a test template
2. **Parameter Validation**: Ensure all parameters are handled correctly
3. **Documentation**: Update template documentation
4. **User Testing**: Get feedback from intended users
5. **Production Deployment**: Release to live templates

<Tip>
  Keep a local development environment set up for quick iterations. The compilation and upload process becomes much faster with practice.
</Tip>

<Warning>
  Always test compiled diagrams thoroughly before uploading to production templates. Diagram errors can break template functionality for end users.
</Warning>