Skip to content
This repository has been archived by the owner on Jan 18, 2023. It is now read-only.

Commit

Permalink
update documentation for 1.5
Browse files Browse the repository at this point in the history
  • Loading branch information
@nahtnam
nahtnam committed Oct 21, 2019
1 parent 1d3eca0 commit aae0c6d
Show file tree
Hide file tree
Showing 8 changed files with 102 additions and 121 deletions.
14 changes: 6 additions & 8 deletions guides/error-handling.md
View file
Expand Up @@ -12,16 +12,14 @@ Error handling is done mostly by throwing a new Error. Each route is wrapped wit
Simply import [`createError`](/docs/boom/create-error) and throw it at any point. createError will create a boom error resulting in a pretty JSON output.

```js
const { light, Route, createError } = require('light');
const { route, createError } = require('light');

class Index extends Route {
async handler() {
throw createError(401, 'sorry, you cannot access this route');
return 'it will not get to me :(';
}
}
const { handler } = route();

module.exports = light(Index);
module.exports = handler(() => {
throw createError(401, 'sorry, you cannot access this route');
return 'it will not get to me :(';
});
```

This will result in JSON which looks like this:
Expand Down
16 changes: 7 additions & 9 deletions guides/getting-started.md
View file
Expand Up @@ -38,17 +38,15 @@ Once you've installed light, all `.js` files under the `routes` folder will be u
To get started, populate `routes/index.js`.

```js
const { light, Route } = require('light');
const { route } = require('light');

class Index extends Route {
async handler() {
return {
hello: 'world',
};
}
}
const { handler } = route();

module.exports = light(Index);
module.exports = handler(() => {
return {
hello: 'world',
};
});
```

Run `npm run dev` to start the development server. You should see an output in your terminal similar to the one below.
Expand Down
23 changes: 10 additions & 13 deletions guides/middleware.md
View file
Expand Up @@ -22,24 +22,21 @@ const checkAuth = async (req, res) => {
}
```

To include middleware in your route, simply add it as a property array.
To include middleware in your route, simply call the `middleware` function.

```js
const { light, Route } = require('light');
const { route } = require('light');

class Index extends Route {
get middleware() {
return [ checkAuth ]; // you can have multiple middleware
}
const { handler, middleware } = route();

async handler() {
return {
isAuthenticated: this.req.isAuthenticated,
};
}
}
middleware(checkAuth, someOtherMiddleare);
middleware(whoopsForgotOne);

module.exports = light(Index);
module.exports = handler((req) => {
return {
isAuthenticated: req.isAuthenticated,
};
});
```

## Express and Koa Support
Expand Down
12 changes: 4 additions & 8 deletions guides/misc/apollo.md
View file
Expand Up @@ -18,7 +18,7 @@ npm install apollo-server-micro graphql
Once done, all you need to do is create a `graphql.js` file under the routes folder. Inside this, add the following starter code:

```js
const { light, Route } = require('light');
const { route } = require('light');
const { ApolloServer, gql } = require('apollo-server-micro');

const typeDefs = gql`
Expand All @@ -38,12 +38,8 @@ const resolvers = {
const apolloServer = new ApolloServer({ typeDefs, resolvers });
const graphqlHandler = apolloServer.createHandler();

class graphql extends Route {
async handler() {
return graphqlHandler(this.req, this.res);
}
}
module.exports = light(graphql);
const { handler } = route();
module.exports = handler((req, res) => graphqlHandler(req, res));
```

Most of the code that is provided is the starter code for Apollo. The only light related code is the `module.exports` at the bottom which simply tells light to run the following graphql handler when the route is `/graphql` with either GET (for the graphical interface) or POST (for the actual queries). *As always, if you are hosting on a serverless platform, you will need to point the route `/graphql` to this file.*
Most of the code that is provided is the starter code for Apollo. The only light related code is the `module.exports` at the bottom (and the line above) which simply tells light to run the following graphql handler when the route is `/graphql` with either GET (for the graphical interface) or POST (for the actual queries). *As always, if you are hosting on a serverless platform, you will need to point the route `/graphql` to this file.*
21 changes: 8 additions & 13 deletions guides/plugins.md
View file
Expand Up @@ -28,19 +28,14 @@ As you can see, unlike middleware, with plugins we can run code both before and
Finally, we simply list the logger as plugin in the route.

```js
const { light, Route } = require('light');
const { route } = require('light');
const { handler, plugin } = route();

class Index extends Route {
get plugins() {
return [ logger ]; // you can have multiple plugins
}
plugin(logger);

async handler() {
return {
hello: 'world',
};
}
}

module.exports = light(Index);
module.exports = handler(() => {
return {
hello: 'world',
};
}));
```
26 changes: 9 additions & 17 deletions guides/query.md
View file
Expand Up @@ -14,20 +14,18 @@ If there are multiple query parameters with the same name, it will return an arr
Simply call the query function inside of your handler.

```javascript
const { light, Route } = require('light');
const { route, query } = require('light');

class Index extends Route {
async handler() {
const { id, name } = await this.query();
const { handler } = route();

return {
id,
name,
};
}
}
module.exports = handler(((req, res) => {
const { id, name } = await query(req.url);

module.exports = light(Index);
return {
id,
name,
};
});
```
After starting the dev server, you can make a request to [localhost:3000/?id=123&name=light](http://localhost:3000/?id=123&name=light) and expect a response of
Expand All @@ -40,9 +38,3 @@ After starting the dev server, you can make a request to [localhost:3000/?id=123
```
Note that by default all query parameters are strings, and you will need to cast them as necessary.

If you need to use the query function outside of the route such as a middleware or plugin, you can also call query on the route class directly.

```javascript
const { id, name } = await Route.query(someURL);
```
38 changes: 17 additions & 21 deletions guides/routes.md
View file
Expand Up @@ -5,46 +5,42 @@ subtitle: the main entry point for your endpoints

## Introduction

Every light route must export a class with a `handler` function (which can be an async function) which is responsible for handling request. The handler will receive have access to `this.req` (IncomingMessage) and `this.res` (ServerResponse) (these may vary between different environments).
Every light route must export the `handler` function with a callback function inside (which can be an async function) which is responsible for handling request. The handler will receive have access to `req` (IncomingMessage) and `res` (ServerResponse) as parameters (these may vary between different environments).

## Req/Res

The `this.req` and `this.res` variables are standard IncomingMessage and ServerResponse objects. In some environments, properties may be added or missing. For example, in AWS/Netlify mode, the `this.req` object will be missing some request and response properties because they were casted from event and context. You should only use properties that you know are going to be available in production.
The `req` and `res` variables are standard IncomingMessage and ServerResponse objects. In some environments, properties may be added or missing. For example, in AWS/Netlify mode, the `req` object will be missing some request and response properties because they were casted from `event` and `context`. You should only use properties that you know are going to be available in your production environment.

## Return

If you choose to `return` from the function (instead of `send`ing), you must return a valid response. Whatever value that is returned will be serialized and sent as a response. You can choose to return JSON, String, or any other type that [micro](https://github.com/zeit/micro) supports under the hood.

```js
const { light, Route } = require('light');
const { route } = require('light');

class Index extends Route {
async handler() {
// this.req and this.res variables are available here
const { handler } = route();

return {
hello: 'world',
};
// or
return 'hello world';
}
}
module.exports = handler(async (req, res) => {
// req and res variables are available here

module.exports = light(Index);
return {
hello: 'world',
};
// or
return 'hello world';
});
```

## Send

Additionally you may use `micro`'s send function to return different kinds of responses. The send function can be imported from light and used anywhere in the handler. See [micro's documentation](https://github.com/zeit/micro#sendres-statuscode-data--null) for more details.

```js
const { light, Route, send } = require('light');
const { route, send } = require('light');

class Index extends Route {
async handler() {
send(this.res, 200, { hello: 'world' });
}
}
const { handler } = route();

module.exports = light(Index);
module.exports = handler(async (req, res) => {
send(res, 200, { hello: 'world' });
});
```
73 changes: 41 additions & 32 deletions website/src/pages/index.jsx
View file
Expand Up @@ -134,17 +134,16 @@ export default class Index extends React.Component {
</div>
</div>
<div className="w-full md:w-1/2 shadow-xl text-center m-4 md:m-0 rounded overflow-x-auto">
<CodeBlock language="javascript" value={`const { light, Route } = require('light');
<CodeBlock language="javascript" value={`const { route } = require('light');
const { handler, middleware, plugin } = route();
class Index extends Route {
async handler() {
return {
hello: 'world',
};
}
}
module.exports = light(Index);`} />
middleware(auth, cors);
plugin(errorHandling);
module.exports = handler((req, res) => {
return {
hello: 'world',
};
});`} />
</div>
</div>
</div>
Expand Down Expand Up @@ -201,38 +200,48 @@ module.exports = light(Index);`} />
<span className="flex-1" />
</div>
<div className="w-full md:w-1/2 shadow-xl text-center m-4 md:m-0 rounded overflow-x-auto">
<CodeBlock language="javascript" value={`const { light, Route } = require('light');
<CodeBlock language="javascript" value={`const { route } = require('light');
const { handler, middleware, plugin } = route();
${selectedDeploy.code ? `${selectedDeploy.code}` : ''}
class Index extends Route {
async handler() {
return {
hello: 'world',
};
}
}
module.exports = light(Index);`} />
middleware(auth, cors);
plugin(errorHandling);
module.exports = handler((req, res) => {
return {
hello: 'world',
};
});`} />
</div>
</div>
</div>
<div className="pt-12 md:block md:m-0 hidden">
<div className="container mx-auto flex-col-reverse md:flex-row flex-wrap md:flex">
<div className="w-full md:w-2/3 text-center px-2 m-4 md:m-0">
<Embed source={ `const { light, Route } = require('light');
process.env.LIGHT_ENV = 'runkit';
class Index extends Route {
async handler() {
return {
hello: 'world',
};
}
}
<Embed source={ `const { route } = require('light');
const { handler, middleware, plugin } = route();
process.env.LIGHT_ENV='runkit';
module.exports = light(Index);` } mode='endpoint' />
/*
// middleware is run before your handler
middleware(
(req, res) => console.log(req.url),
);
// plugins wrap your handlers (and middleware)
plugin(
(fn) => async (req, res) => {
const before = Date.now();
await fn(req, res)
const after = Date.now();
console.log('the request took', after - before, 'ms');
},
);
*/
module.exports = handler((req, res) => {
return {
hello: 'world',
};
});` } mode='endpoint' />
</div>
<div className="flex flex-col w-full md:w-1/3 text-center p-4 pb-0">
<span className="flex-1" />
Expand Down

0 comments on commit aae0c6d

Please sign in to comment.