Programmatic Usage Documentation

[lukeshumard]

I've been using Hazel, but I believe there's an error in the documentation for Programmatic Usage. The following code from the README does not work as expected. The request hangs and never receives a response.

const hazel = require('hazel-server')

http.createServer((req, res) => {
  hazel(req, res)
})

Diagnostics

The issue is that package.json specifies the main file as lib/index.js. Using require.resolve also confirms that this file is loaded when calling the module programatically. lib/index.js exports a composed function with a config object of options as its parameter and then expects to receive a req and res as the next function parameters.

With the above code block, this means that req is being passed as the config and the route handler is never called. This explains why the request never receives a response.

This works with the auto-deploy on Vercel because vercel.json uses the api/index.js file to use lib/server.js, which loads the necessary config.

Potential Solutions

I have 3 different ideas on how this could potentially be resolved.

1. Change module resolution to lib/server.js

By switching the module to resolve to lib/server, the API would work as intended. However, this would be a breaking change and require migration from existing projects.

2. Update Programmatic Usage example

The package will be left as is, but documentation will need to be modified to show that a config will need to be specified.

const hazel = require('hazel-server')

http.createServer((req, res) => {
  const config = { account: 'vercel', repository: 'hazel' }
  hazel(config)(req, res)
})

The option could also be shown to resolve directly to lib/server if the developer wants the same experience as the deploy button's zero-config magic.

const hazel = require('hazel-server/lib/server')

http.createServer((req, res) => {
  hazel(req, res)
})

3. Allow a config to get passed to lib/index.js

To have both the zero-config magic and manual configuration in using Programmatic Usage, lib/index.js could be refactored to include an optional config parameter that would overwrite any environment variables set.

const hazel = require('hazel-server')

http.createServer((req, res) => {
  hazel(req, res, { account: 'vercel' })
})

I've made a repository to show this issue and easily reproduce. I'm happy to submit a PR with any changes to help improve this feature.