Skip to content

Latest commit

 

History

History
182 lines (126 loc) · 4.44 KB

developer-documentation.md

File metadata and controls

182 lines (126 loc) · 4.44 KB

Developer Documentation

Prerequisites

  • Node.js 20.x
  • npm
  • A Screenly account with API access

Installation

  1. Install dependencies:

    npm install

  2. Set up pre-commit hooks:

    # Install husky and lint-staged
npm install -D husky lint-staged

# Initialize husky
npm run prepare

# Add pre-commit hook
npx husky add .husky/pre-commit "npm test && npm run lint"

# Install linting tools
npm install -D eslint prettier markdownlint-cli

  3. Configure your Screenly API key:

    • Get your API key from Screenly. For instructions on how to get your API key, see this guide.
    • When setting up the Zapier integration, you'll be prompted to enter this API key

Available Scripts

  • npm test - Run unit tests with coverage
  • npm run test:watch - Run tests in watch mode
  • npm run lint - Run ESLint
  • npm run format - Format code with Prettier
  • npm run clean - Clean up generated files
  • npm run build - Compile TypeScript code
  • npm run deploy - Deploy to Zapier
  • npm run prepare - Install git hooks (runs automatically after npm install)

Visual tests are only run in CI environment:

  • npm run test:visual - Displays information about visual tests
  • npm run test:visual:ci - Runs visual tests (CI only)

Code Quality

The project uses several tools to ensure code quality:

  • ESLint - For code linting
  • Prettier - For code formatting
  • Vitest - For testing
  • Husky - For git hooks
  • lint-staged - For running checks on staged files
  • markdownlint - For markdown formatting

These run automatically on commit, but you can also run them manually:

npm run lint    # Check code style
npm run format  # Fix code formatting

Git Hooks

Pre-commit hooks are set up to:

  • Run unit tests
  • Lint JavaScript files
  • Format code with Prettier
  • Check markdown formatting
  • Run tests

The hooks are configured in:

  • .husky/pre-commit - Hook scripts
  • package.json - lint-staged configuration
  • .eslintrc.js - ESLint rules
  • .prettierrc - Prettier configuration
  • .markdownlint.json - Markdown linting rules

Visual Testing

Visual tests are automatically run in CI and generate screenshots of:

  • Upload Asset Form
  • Complete Workflow Form
  • Cleanup Confirmation Form

These tests are skipped locally to avoid environment-specific issues.

Best Practices

  1. Dependency Management

    • Never edit package-lock.json manually
    • Use npm commands to manage dependencies:
    npm install <package>        # Add dependency
npm install -D <package>     # Add dev dependency
npm update <package>         # Update package
npm uninstall <package>      # Remove package

  2. Code Style

    • ESLint and Prettier are configured
    • Formatting is automatically handled on commit
    • Run npm run format to manually format code

  3. Testing

    • Maintain test coverage above 80%
    • Write tests for new features
    • Visual tests are CI-only

  4. Git Workflow

    • Commits are automatically linted
    • Visual tests run on pull requests
    • CI checks must pass before merge

Setting up Zapier Deployment

  1. Get your Zapier Deploy Key:

    zapier login
zapier register "Screenly"  # Only needed for first-time setup

  2. Add the deploy key to GitHub:

    • Go to your repository's Settings > Secrets > Actions
    • Add a new secret named ZAPIER_DEPLOY_KEY
    • Paste your deploy key as the value

Deployment

Compile the TypeScript code so that JavaScript code will be generated:

npm run build

The command will create a new folder called dist/, which is referenced by index.js.

The integration is automatically deployed to Zapier when a new version tag is pushed to GitHub.

  1. Create and push a new version tag:

    git tag -a v0.5.0 -m "New release"
git push origin v0.5.0

  2. The GitHub Action will:

    • Run tests
    • Deploy to Zapier

If you wish to deploy the integration privately, you can do so by following the steps below, given that you have completed the initial setup steps above.

npm run build && zapier push

Version Management

  • Use semantic versioning (MAJOR.MINOR.PATCH)
  • Tag format: v*.*.* (e.g., v0.5.0, v1.0.0)
  • Pre-release versions: Use -beta, -alpha suffixes

License

See LICENSE file for details.