zap-step

Boilerplate for writing, testing and packaging Zapier JavaScript steps.

Features

• Lets you write your step as a function that is testable
• Packages up your code and dependencies (via Parcel) into a single file
• Helpers for testing your functions
• TypeScript types for your functions and tests
• Builds with Parcel so you can take advantage of all the tooling you enjoy, like Babel, TypeScript, etc.

Writing Zap steps with zap-step

1. Write a function that you want to run on Zapier.

• Instead of using an inputData global variable, the input data is passed as the first argument to your function.
• Instead of setting the output variable (or writing a naked return outside a function), the return value of your function is used as the output.
• Export your function as default to make it the entry point for the zap step.

The old way, before zap-step

// 👎 Code
const addBusinessDays = (timestamp, amount) => {
  const date = new Date(timestamp)
 
  const hours = date.getHours()
  const numWeekDays = 0
 
  while (numWeekDays < amount) {
    date.setDate(date.getDate() + 1)
    date.setHours(hours)
    if (date.getDay() == 6 || date.getDay() == 0) numWeekDays++
  }
 
  return date
}
 
return { tenBusinessDaysAfter: addBusinessDays(parseInt(inputData.eventDate), 10) }
 
// Tests
// ??? 👎👎 Good luck with that

The new way, with zap-step

// 👍 tenBusinessDaysAfter.js
import { addBusinessDays } from 'date-fns'
 
export default ({ eventDate }) => ({
  tenBusinessDaysAfter: addBusinessDays(parseInt(eventDate), 10)
})
 
 
// Tests 👌
import tenBusinessDaysAfter from '../src/tenBusinessDaysAfter'
 
describe('tenBusinessDaysAfter', () => {
  const startDate = new Date('January 10, 2019')
  const endDate   = new Date('January 20, 2019')
 
  it('returns a date ten business days after the input', () => {
    expect(tenBusinessDaysAfter(startDate)
      .to.eql({ tenBusinessDaysAfter: endDate })
  })
})

2. Write your tests

To test functions besides your main one, use named exports.

// myStep.js
export function myDifficultLogic    () { /*...*/ }
export function otherDifficultLogic () { /*...*/ }
 
export default ({ eventDate }) => ({
  myDifficultLogic:    myDifficultLogic(),
  otherDifficultLogic: otherDifficultLogic(),
})
 
 
// test/myStep.test.js
import { myDifficultLogic, otherDifficultLogic } from '../myStep'
 
describe('myDifficultLogic', () => {
  // ...
})
 
describe('otherDifficultLogic', () => {
  // ...
})

3. Use TypeScript types

Use types to help guide your implementation and testing.

// Code
import { ZapStep } from 'zap-step'
 
const myFunc: ZapStep = ({ eventDate }) => ({
  myDifficultLogic:    myDifficultLogic(),
  otherDifficultLogic: otherDifficultLogic(),
})
 
export default myFunc

4. zapify to bundle it up

yarn zapify src/tenBusinessDaysAfter.js dist/tenBusinessDaysAfter.js

The zapify command builds & bundles your file with Parcel, then adds some special code to make it work as a Zapier JS code step.

5. Copy & paste into Zapier

Copy & paste the contents of your built file into a Zapier zap step.

Testing bundled (and hand-written) steps

Using the provided zapStep helper, one can test a file that contains code for a Zapier step. This can handle code bundled with our zapify command, as well as code written by hand.

Provide it with a file name and it will read the file and eval the code inside an environment that simulates a Zapier step.

import zapStep from 'zap-step'
 
const input = { /*...*/ }
 
const output = zapStep('dist/myZapStep.js', input)