A framework that allows better code structure and routing for ZEIT integrations.
After reading the code of a bunch of integrations and trying write some myself, I noticed that the main body of the withUiHook handler had a ton of logic and it became hard to read. Also there was logic that was repeated between actions and even between integrations. Therefore, as I was working on my first integration, I started abstacting some of that logic. After seeing how well it worked for me, I decided to make it a package so I can use it to develop future integration.
NOTE: This is very much WIP. I started developing it during the ZEIT Hackathon, so I had limited time. There's full TypeScript support but cleaner code and better docs coming soon
$ yarn add now-integration
or
$ npm install now-integration
The main part of the package is the Integration class. This class is the backbone of the application.
import Integration, {requireProject} from 'now-integration';
import {htm} from '@zeit/integration-utils';
const app = new Integration({
defaultRoute: ({utils}) => htm`<Page>You are logged in! Your token is ${utils.projectStore.token}</Page>`
});
app.extend(requireProject());
app.use('login/:method', async ({utils, zeitClient, payload}, next) => {
if (utils.params.method === 'token') {
const token = utils.get('token');
utils.projectStore.token = token;
await utils.saveStore();
next();
} else {
// Login some other way
}
});
app.use(async ({utils}, next) => {
if (utils.projectStore.token) {
next();
} else {
return utils.renderRoute('view/login');
}
});
app.render('view/login', async ({payload, zeitClient, utils}) => {
return htm`
<Page>
<H2>Please login to continue</H2>
<Input name="token" label="token"/>
<Button action="login/token">Save Token</Button>
</Page>
`;
});
export default app.handler;Type: object
Type: [handler](#handler)
A handler that will be called if no other route matches. Can be used as the default view route.
Adds middleware handler(s) to be ran. These usually don't end the call, but handle actions and provide context. If needed they can intercept the flow and end the call.
Type: string | string[] Optional
A pattern or a list of patterns to match against the action string. The handler(s) will only be called if at least one pattern matches.
If the pattern includes a parameter login/:method, the parameters will be included in the utils object under params
If no pattern is provided, the handler(s) will be called on every action
Type: [handler](#handler)
The handler(s) that will be called.
The middleware handlers receive an extra parameter next, which they can call to pass the rendering to the next handler. If the handler needs to stop the flow, it can return the htm element instead of calling next(). That will end the call without any other handler being called.
Adds view handlers. These handlers need to return a valid htm element. That element will be returned from the call.
Type: string | string[]
A pattern or a list of patterns to match against the action string. The handler(s) will only be called if at least one pattern matches.
If the pattern includes a parameter login/:method, the parameters will be included in the utils object under params
Note: at least one pattern is required for these handlers
Type: [handler](#handler)
The handler(s) that will be called.
Unlike middleware handlers, these handlers have to returna valid htm element that will be return from to the UI hook.
Extend the funcionality of the integration by adding a plugin. All this does is group some middleware and view handlers based on the purpose they serve for cleaner code
Type: (app: Integration) => void
A function that will be called with the integration instance. In this function, the plugin can add middleware or view handlers.
Type: (req, res) => void
This is a regular http server handler that can be exported from the main file. It includes the withUiHook helper provided by @zeit/integration-utilsintegration-utils).
Type: (options) => Promise<any>
A handler that returns a valid htm element
Middleware handlers receive an extra parameter next that they can call instead of returning a value: (options, next) => Promise<any | void>
Handlers are called in the order they were added. First all the middleware ones and then the view ones until one matches. Be mindful about the order in which you add them.
Type: object
Type: ZeitClient
The client provided by withUiHook of @zeit/integration-utils
Type: object
The payload provided by withUiHook of @zeit/integration-utils
Type: [utils](#utils)
A class with various utilities described below
The utils class available to every handler
Type: object
An object that starts empty at the start of the call and will be passed to every handler
Can be used to pass information downstream
Type: object Optional
An object that contains key/value pairs for all params matched in the handler's pattern
For example an action view/login/token matched by the pattern view/login/:method would yield:
console.log(utils.params);
// => {method: 'token'}Type: (route) => Promise<any>
A method that will render the provided route and return the result. This can be used when handlers want to terminate the flow early or redirect it:
if (!token) {
return utils.renderRoute('login');
} else {
// Render the regular view
next();
}Type: string
The exact route to render
Note: The route will try to match a view handler exactly. Won't match middleware handlers
Type: object
The result of await zeitClient.getMetadata().
Will be passed to every handler
Type: object
Equivalent to store[projectId].
A convenient way to save project-scoped data
Type: () => Promise<object>
Equivalent of calling await zeitClient.saveMetadata(utils.store)
There is no need to set the result of the call back to the store
utils.store.token = 'my-token';
utils.projectStore.token = 'my-project-token';
await utils.saveStore();
// ...Type: (key) => string
Equivalent to payload.clientState[key]
Type: string Optional
Equivalent to payload.projectId
Type: string
Equivalent to payload.action
The package also includes two plugins for very common functionalities:
import Integration, {requireProject} from 'now-integration';
const app = new Integration({defaultRoute});
app.extend(requireProject());
export default app.handler;Adds middleware that will ensure the integration is scoped to a project. If it is not, it will render a view including a project switcher.
Type: object Optional
Type: htm Component
View to render when the user is not scoped to a project instead of the default one
Takes no props
import Integration, {requireTokenLogin} from 'now-integration';
const app = new Integration({defaultRoute});
app.extend(requireTokenLogin({
projectScoped: true,
tokens: [{
key: 'appKey',
name: 'You application key'
}, {
key: 'appSecret',
name: 'Your application secret'
}],
testTokens: async (tokens) => {
try {
await myClient.ensureValidTokens(tokens.appKey, tokens.appSecret);
return false;
} catch (error) {
return 'Something went wrong';
}
}
}));
export default app.handler;Adds middleware that will ensure the user has logged in by providing some token(s) before letting them access any of the routes.
Type: object Optional
Type: boolean
Default: false
Wether or not the plugin should require a different token for each project.
Usually used together with [requireProject](#requireProject)
Type: { key: string, name: string }[]
Default: [{ key: 'token', name: 'API Token' }]
A list of tokens to request from the user
Type: string
The key to use when saving the token in the store
Type: string
The label to display for the <Input/> element when requesting the token
Type: (tokens) => Promise<false | string>
Default: () => false
A function that will be called with the tokens when the user submits the form.
It should return false if the tokens are valid, or a string with a message to be displayed to the user when asking for the tokens again.
The tokens will not be saved until testTokens returns false
Type: {[key: string]: string}
An object containing all the tokens. The keys used are the ones provided in the [tokens](#tokens) object and the values are the user's inputs
Type: htm Component
View to render if the user doesn't have all the required tokens instead of the default one.
error(string) - An error messagemessage(string) - A informational message (You have logged out successfullywhen the user logs out)title(string) - A title to appear above the formtokens(object) - The tokens to display
This plugin provides the following action:
logout - Use this to erase the user's token and bring them back to the login screen
htm`<Button action="logout">Logout</Button>`ZEIT Integrations built using this module: