Skip to content

Commit c6064a5

Browse files
naorpelednaorpeled
authored
docs: add Docusaurus documentation site deployed via GitHub Pages (#322)
1 parent 259e6b6 commit c6064a5

60 files changed

Lines changed: 23814 additions & 1485 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.eslintignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,7 @@ coverage
22
node_modules
33
__tests__
44
*.test.js
5-
dist
5+
dist
6+
7+
# Docs site is a self-contained sub-project with its own toolchain
8+
website

‎.github/workflows/deploy-docs.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: Deploy Docs
2+
3+
# Builds the Docusaurus site in website/ and publishes it to GitHub Pages.
4+
# Requires the repository's Pages source to be set to "GitHub Actions"
5+
# (Settings -> Pages -> Build and deployment -> Source).
6+
7+
on:
8+
push:
9+
branches:
10+
- main
11+
paths:
12+
- 'website/**'
13+
- '.github/workflows/deploy-docs.yml'
14+
workflow_dispatch:
15+
16+
# Allow only one concurrent deployment, skipping runs queued between the run
17+
# in-progress and latest queued. Do not cancel in-progress runs.
18+
concurrency:
19+
group: pages
20+
cancel-in-progress: false
21+
22+
jobs:
23+
build:
24+
name: Build Docusaurus
25+
runs-on: ubuntu-latest
26+
defaults:
27+
run:
28+
working-directory: website
29+
steps:
30+
- uses: actions/checkout@v4
31+
with:
32+
fetch-depth: 0
33+
- uses: actions/setup-node@v4
34+
with:
35+
node-version: 20
36+
cache: npm
37+
cache-dependency-path: website/package-lock.json
38+
- name: Install dependencies
39+
run: npm ci
40+
- name: Build website
41+
run: npm run build
42+
- name: Upload Pages artifact
43+
uses: actions/upload-pages-artifact@v3
44+
with:
45+
path: website/build
46+
47+
deploy:
48+
name: Deploy to GitHub Pages
49+
needs: build
50+
runs-on: ubuntu-latest
51+
permissions:
52+
pages: write # to deploy to Pages
53+
id-token: write # to verify the deployment originates from an appropriate source
54+
environment:
55+
name: github-pages
56+
url: ${{ steps.deployment.outputs.page_url }}
57+
steps:
58+
- name: Deploy to GitHub Pages
59+
id: deployment
60+
uses: actions/deploy-pages@v4

‎.prettierignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,7 @@ coverage
22
node_modules
33
__tests__
44
*.test.js
5-
dist
5+
dist
6+
7+
# Docs site is a self-contained sub-project with its own toolchain
8+
website

‎README.md‎

Lines changed: 51 additions & 1483 deletions
Large diffs are not rendered by default.

‎assets/lambda-api-logo.png‎

2.85 KB
Loading

‎website/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎website/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Lambda API Documentation Site
2+
3+
The [Lambda API](https://github.com/jeremydaly/lambda-api) documentation site, built with
4+
[Docusaurus](https://docusaurus.io/). It is published to GitHub Pages at
5+
**https://jeremydaly.github.io/lambda-api/** by the
6+
[`deploy-docs.yml`](../.github/workflows/deploy-docs.yml) workflow on every push to `main`
7+
that touches `website/`.
8+
9+
Documentation content lives in [`docs/`](./docs); the sidebar is defined in
10+
[`sidebars.ts`](./sidebars.ts) and site config in [`docusaurus.config.ts`](./docusaurus.config.ts).
11+
12+
## Local development
13+
14+
```bash
15+
cd website
16+
npm install
17+
npm start
18+
```
19+
20+
Starts a local dev server with hot reload at `http://localhost:3000/lambda-api/`.
21+
22+
## Build
23+
24+
```bash
25+
npm run build # outputs static files to website/build
26+
npm run serve # preview the production build locally
27+
npm run typecheck # type-check the TypeScript config/components
28+
```
29+
30+
The production build fails on broken internal links (`onBrokenLinks: 'throw'`), so a clean
31+
`npm run build` is the gate to keep green.
32+
33+
## Search
34+
35+
Search is provided offline by
36+
[`@easyops-cn/docusaurus-search-local`](https://github.com/easyops-cn/docusaurus-search-local) —
37+
the index is generated at build time, so no Algolia account is required.

‎website/docs/api-reference/app-configuration.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: App Configuration Options
3+
description: Reference table of options passed when initializing a lambda-api instance.
4+
---
5+
6+
These options are passed to `require('lambda-api')({ ... })` when you instantiate the API.
7+
8+
| Property | Type | Description |
9+
| -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
10+
| base | `String` | Base path for all routes, e.g. `base: 'v1'` would prefix all routes with `/v1` |
11+
| callbackName | `String` | Override the default callback query parameter name for JSONP calls |
12+
| logger | `boolean` or `object` | Enables default [logging](/docs/logging/overview) or allows for configuration through a Logging Configuration object. |
13+
| mimeTypes | `Object` | Name/value pairs of additional MIME types to be supported by the `type()`. The key should be the file extension (without the `.`) and the value should be the expected MIME type, e.g. `application/json` |
14+
| serializer | `Function` | Optional object serializer function. This function receives the `body` of a response and must return a string. Defaults to `JSON.stringify` |
15+
| version | `String` | Version number accessible via the `REQUEST` object |
16+
| errorHeaderWhitelist | `Array` | Array of headers to maintain on errors |
17+
| s3Config | `Object` | Optional object to provide as config to S3 sdk. [S3ClientConfig](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-s3/interfaces/s3clientconfig.html) |
18+
19+
See the full [Configuration](/docs/core-concepts/configuration) guide for details and examples.

‎website/docs/api-reference/request-properties.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Request Properties
3+
description: Reference table of all properties available on the lambda-api REQUEST object.
4+
---
5+
6+
The `REQUEST` object contains a parsed and normalized request from API Gateway. It contains the following values by default.
7+
8+
| Property | Description |
9+
| -------- | ----------- |
10+
| `app` | A reference to an instance of the app |
11+
| `version` | The version set at initialization |
12+
| `id` | The `awsRequestId` from the Lambda `context` |
13+
| `interface` | The interface being used to access Lambda (`apigateway`, `alb`, or `edge`) |
14+
| `params` | Dynamic path parameters parsed from the path (see [path parameters](/docs/core-concepts/path-parameters)) |
15+
| `method` | The HTTP method of the request |
16+
| `path` | The path passed in by the request including the `base` and any `prefix` assigned to routes |
17+
| `query` | Querystring parameters parsed into an object |
18+
| `multiValueQuery` | Querystring parameters with multiple values parsed into an object with array values |
19+
| `headers` | An object containing the request headers (keys lowercased for HTTP/2; multi-value headers concatenated with a comma) |
20+
| `rawHeaders` | An object containing the original request headers (property case preserved) |
21+
| `multiValueHeaders` | An object containing header values as multi-value arrays |
22+
| `body` | The body of the request, automatically decoded if base64-encoded and parsed based on `content-type` (`JSON.parse` for JSON, `querystring` for URL-encoded, otherwise plain text) |
23+
| `rawBody` | If `isBase64Encoded` is `true`, a copy of the original, base64-encoded body |
24+
| `route` | The matched route of the request |
25+
| `requestContext` | The `requestContext` passed from the API Gateway |
26+
| `pathParameters` | The `pathParameters` passed from the API Gateway |
27+
| `stageVariables` | The `stageVariables` passed from the API Gateway |
28+
| `isBase64Encoded` | The `isBase64Encoded` boolean passed from the API Gateway |
29+
| `auth` | An object with the `type` and `value` of an authorization header. Supports `Bearer`, `Basic`, `OAuth`, and `Digest` schemas |
30+
| `namespace` or `ns` | A reference to modules added to the app's namespace (see [namespaces](/docs/core-concepts/namespaces)) |
31+
| `cookies` | An object containing cookies sent from the browser |
32+
| `context` | Reference to the `context` passed into the Lambda handler function |
33+
| `coldStart` | Boolean indicating whether the current invocation was a cold start |
34+
| `requestCount` | Integer of total invocations of the current function container (how many times it has been reused) |
35+
| `ip` | The IP address of the client making the request |
36+
| `userAgent` | The `User-Agent` header sent by the client making the request |
37+
| `clientType` | Either `desktop`, `mobile`, `tv`, `tablet`, or `unknown` based on CloudFront's analysis of the `User-Agent` header |
38+
| `clientCountry` | Two-letter country code representing the origin of the request as determined by CloudFront |
39+
| `stack` | An array of function names executed as part of a route's Execution Stack, useful for debugging |
40+
41+
See the full [Request Object](/docs/request-response/request-object) guide for details and examples.

‎website/docs/api-reference/response-methods.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Response Methods
3+
description: Reference table of all methods available on the lambda-api RESPONSE object.
4+
---
5+
6+
The [RESPONSE object](/docs/request-response/response-object) is used to send a response back to the API Gateway. All methods are chainable unless they trigger a response.
7+
8+
| Method | Description | Guide |
9+
| ------ | ----------- | ----- |
10+
| `status(code)` | Sets the HTTP status code returned to API Gateway (defaults to `200`, or `500` on a thrown error) | [Sending responses](/docs/request-response/sending-responses) |
11+
| `sendStatus(code)` | Sets the status code and returns its string representation as the response body | [Sending responses](/docs/request-response/sending-responses) |
12+
| `send(body)` | Triggers the response, sending the contents through as-is | [Sending responses](/docs/request-response/sending-responses) |
13+
| `json(body)` | Sets `content-type` to `application/json` and runs `JSON.stringify()` on the body | [Sending responses](/docs/request-response/sending-responses) |
14+
| `jsonp(body)` | Like `json()` but wraps the result in a callback function for JSONP | [Sending responses](/docs/request-response/sending-responses) |
15+
| `html(body)` | Sets `content-type` to `text/html` and passes through the contents | [Sending responses](/docs/request-response/sending-responses) |
16+
| `type(type)` | Sets the `content-type` header based on a file extension or MIME type string | [Sending responses](/docs/request-response/sending-responses) |
17+
| `header(key, value [,append])` | Sets a response header; supports multi-value arrays and an optional append flag | [Headers and cookies](/docs/request-response/headers-and-cookies) |
18+
| `getHeader(key [,asArray])` | Retrieves a header value (case-insensitive); returns a `string` by default | [Headers and cookies](/docs/request-response/headers-and-cookies) |
19+
| `getHeaders()` | Retrieves the current header object with `array` values | [Headers and cookies](/docs/request-response/headers-and-cookies) |
20+
| `hasHeader(key)` | Returns a boolean indicating whether `key` exists (case-insensitive) | [Headers and cookies](/docs/request-response/headers-and-cookies) |
21+
| `removeHeader(key)` | Removes the header matching `key` (case-insensitive); chainable | [Headers and cookies](/docs/request-response/headers-and-cookies) |
22+
| `getLink(s3Path [, expires] [, callback])` | Returns a promise resolving to a signed S3 URL for the referenced file | [Headers and cookies](/docs/request-response/headers-and-cookies) |
23+
| `cookie(name, value [,options])` | Sets a cookie header; only sets the header (a sending method must be called) | [Headers and cookies](/docs/request-response/headers-and-cookies) |
24+
| `clearCookie(name [,options])` | Expires a cookie; only sets the header (a sending method must be called) | [Headers and cookies](/docs/request-response/headers-and-cookies) |
25+
| `location(path)` | Sets the `Location:` header from a single string argument (encoded before being set) | [Redirects and CORS](/docs/request-response/redirects-and-cors) |
26+
| `redirect([status,] path)` | Triggers a redirection and ends execution; status defaults to `302` | [Redirects and CORS](/docs/request-response/redirects-and-cors) |
27+
| `cors([options])` | Adds CORS headers to the response; an optional `options` object customizes defaults | [Redirects and CORS](/docs/request-response/redirects-and-cors) |
28+
| `error([code], message [,detail])` | Stops execution and returns an error message, optionally with a status code and detail | [Redirects and CORS](/docs/request-response/redirects-and-cors) |
29+
| `etag([boolean])` | Enables Etag generation; returns `304 Not Modified` on a matching `If-No-Match` | [Caching and ETags](/docs/request-response/caching-and-etags) |
30+
| `cache([age] [, private])` | Adds a `cache-control` header; chainable | [Caching and ETags](/docs/request-response/caching-and-etags) |
31+
| `modified(date)` | Adds a `last-modified` header (`true` for now, a `Date`, or a parseable string) | [Caching and ETags](/docs/request-response/caching-and-etags) |
32+
| `attachment([filename])` | Sets `content-disposition` to "attachment", optionally with a filename | [Files and downloads](/docs/request-response/files-and-downloads) |
33+
| `download(file [, filename] [, options] [, callback])` | Combines `attachment()` and `sendFile()` to prompt a file download | [Files and downloads](/docs/request-response/files-and-downloads) |
34+
| `sendFile(file [, options] [, callback])` | Sends a local file, S3 file reference, or `Buffer` to the client | [Files and downloads](/docs/request-response/files-and-downloads) |

0 commit comments

Comments
 (0)