From e62f3008bb8bd0e4d7987bd7a82a7b74afcdc235 Mon Sep 17 00:00:00 2001 From: chronark Date: Thu, 21 Nov 2024 21:00:21 +0100 Subject: [PATCH] docs: engineering docs v1 --- apps/engineering/app/(home)/page.tsx | 23 +++-- apps/engineering/app/docs/layout.tsx | 39 +-------- apps/engineering/app/layout.config.tsx | 11 ++- .../content/docs/api-design/meta.json | 4 + .../content/docs/contributing/index.mdx | 87 +++++++++++++++++++ .../content/docs/contributing/meta.json | 7 ++ .../docs/contributing/sdk-development.mdx | 45 ++++++++++ .../content/docs/contributing/testing.mdx | 28 ++++++ .../content/docs/contributing/versions.mdx | 43 +++++++++ 9 files changed, 233 insertions(+), 54 deletions(-) create mode 100644 apps/engineering/content/docs/contributing/index.mdx create mode 100644 apps/engineering/content/docs/contributing/meta.json create mode 100644 apps/engineering/content/docs/contributing/sdk-development.mdx create mode 100644 apps/engineering/content/docs/contributing/testing.mdx create mode 100644 apps/engineering/content/docs/contributing/versions.mdx diff --git a/apps/engineering/app/(home)/page.tsx b/apps/engineering/app/(home)/page.tsx index ca00343b39..08ff6b1e99 100644 --- a/apps/engineering/app/(home)/page.tsx +++ b/apps/engineering/app/(home)/page.tsx @@ -1,16 +1,13 @@ -import Link from "next/link"; - -export default function HomePage() { +export default function Page() { return ( -
-

Unkey Engineering

-

- You can open{" "} - - /docs - {" "} - and see the documentation.{" "} -

-
+
+
+

+ BUILD BETTER +
APIS FASTER +

+

How we work

+
+
); } diff --git a/apps/engineering/app/docs/layout.tsx b/apps/engineering/app/docs/layout.tsx index c5a6babc8a..f82de8bda8 100644 --- a/apps/engineering/app/docs/layout.tsx +++ b/apps/engineering/app/docs/layout.tsx @@ -1,48 +1,11 @@ import { source } from "@/app/source"; -import { RootToggle } from "fumadocs-ui/components/layout/root-toggle"; import { DocsLayout } from "fumadocs-ui/layouts/docs"; -import { Code, Component, Handshake, Terminal } from "lucide-react"; import type { ReactNode } from "react"; import { baseOptions } from "../layout.config"; export default function Layout({ children }: { children: ReactNode }) { return ( - , - }, - { - title: "Company", - description: "How we work", - url: "/docs/company", - icon: , - }, - { - title: "API Design", - description: "Look and feel", - url: "/docs/api-design", - icon: , - }, - { - title: "Architecture", - description: "How does Unkey work", - url: "/docs/architecture", - icon: , - }, - ]} - /> - ), - }} - > + {children} ); diff --git a/apps/engineering/app/layout.config.tsx b/apps/engineering/app/layout.config.tsx index 80863f68fb..62f980f6dc 100644 --- a/apps/engineering/app/layout.config.tsx +++ b/apps/engineering/app/layout.config.tsx @@ -9,13 +9,18 @@ import type { HomeLayoutProps } from "fumadocs-ui/layouts/home"; */ export const baseOptions: HomeLayoutProps = { nav: { - title: "Unkey Engineering", + title: "Unkey", }, githubUrl: "https://github.com/unkeyed/unkey", links: [ { - text: "Documentation", - url: "/docs", + text: "Contributing", + url: "/docs/contributing", + active: "nested-url", + }, + { + text: "Architecture", + url: "/docs/architecture", active: "nested-url", }, { diff --git a/apps/engineering/content/docs/api-design/meta.json b/apps/engineering/content/docs/api-design/meta.json index 9d8e702976..828c033d30 100644 --- a/apps/engineering/content/docs/api-design/meta.json +++ b/apps/engineering/content/docs/api-design/meta.json @@ -1,3 +1,7 @@ { + "title": "API Design", + "description": "Intuitive and helpful", + "icon": "Terminal2", + "root": true, "pages": ["rpc", "errors"] } diff --git a/apps/engineering/content/docs/contributing/index.mdx b/apps/engineering/content/docs/contributing/index.mdx new file mode 100644 index 0000000000..f2687c3031 --- /dev/null +++ b/apps/engineering/content/docs/contributing/index.mdx @@ -0,0 +1,87 @@ +--- +title: Getting Started +--- +import { Step, Steps } from 'fumadocs-ui/components/steps'; + +### Prerequisites + +You need the following services to run Unkey: + + + + We're currently working on making this optional. + +- [Clerk](https://clerk.com?ref=unkey): Authentication + + +You also need the following tools installed. + +- [Node](https://nodejs.org) +- [pnpm](https://pnpm.io/installation) +- [Docker](https://www.docker.com/products/docker-desktop) + +### Developing Unkey + + + #### Repository + Clone the [repo](https://github.com/unkeyed/unkey) + + ```bash + git clone https://github.com/unkeyed/unkey + ``` + + + + + + #### Install + ```bash + cd unkey + corepack enable + pnpm install + ``` + + + + + #### Setup local development + Unkey provides a CLI to setup our local development environment. Run the following command in your terminal: + + ```bash + pnpm local + ``` + + Docker must be running for us to spin up the databases and supporting services. + + + You will be prompted to enter the following values: + + - `CLERK_SECRET_KEY`: Your Clerk secret key. + - `NEXT_PUBLIC_CLERK_PUBLIC_KEY`: Your Clerk public key. + + + + We will create the required `.env` files depending on the selection you've made. + + + + +### About pnpm local command + +If you have already set up Unkey locally once and wish to bypass the manual input questions the next time, you can do so by using flags with the pnpm local command. + + ```bash + pnpm local [options] + ``` + +List of available options: + +- `--service=`: Specifies which part of the application to develop. The values are `dashboard`, `api`, or `www` + +- `--skip-env`: Skips the environment setup prompt if specified. + +Example: + + ```bash + pnpm local --service=dashboard --skip-env + ``` diff --git a/apps/engineering/content/docs/contributing/meta.json b/apps/engineering/content/docs/contributing/meta.json new file mode 100644 index 0000000000..20bc193e01 --- /dev/null +++ b/apps/engineering/content/docs/contributing/meta.json @@ -0,0 +1,7 @@ +{ + "title": "Contributing", + "description": "oss/acc", + "icon": "GitPullRequest", + "root": true, + "pages": ["index", "sdk-development", "testing", "versions"] +} diff --git a/apps/engineering/content/docs/contributing/sdk-development.mdx b/apps/engineering/content/docs/contributing/sdk-development.mdx new file mode 100644 index 0000000000..5f3bd1011b --- /dev/null +++ b/apps/engineering/content/docs/contributing/sdk-development.mdx @@ -0,0 +1,45 @@ +--- +title: SDK development +description: Information for Unkey SDK developers +--- + +# Telemetry + +Unkey collects anonymous telemetry data to help us understand usage of the framework. If you're authoring an SDK, you should record usage information and send it via `Upstash-Telemetry` headers. + +### Typescript libraries + +The Unkey Typescript library `@unkey/api` is already set up to collect telemetry data. If you're writing a new SDK for a framework that makes use of that library +under the hood, you just need to enable the user to disable telemetry; otherwise, pass it in the constructor. You can see an example of this via the Next.js SDK +[here](https://github.com/unkeyed/unkey/blob/main/packages/nextjs/src/index.ts#L99). + +### Telemetry request headers + +Unkey records telemetry data via three headers. You can see an example of how this is used in the Typescript SDK [here](https://github.com/unkeyed/unkey/blob/main/packages/api/src/client.ts#L138) + + +Comma-separated list of strings recording SDKs. Can be multiple SDKs; for instance, the Next.js SDK will record both the Next.js SDK version and +Typescript SDK version. + + + +Referring to the platform where the calling application is deployed. + +For example: `Vercel`, `Cloudflare`, `AWS`, `Deno` + + + +Referring to the programming runtime. + +For example: `edge-light`, `node@18`, `node@20.0.1` + + + +```bash Sending Telemetry +curl -XPOST 'https://api.unkey.dev/v1/keys.verifyKey' \ + -H "Content-Type: application/json" \ + -H "Unkey-Telemetry-SDK: @unkey/api@1.10.0" \ + -H "Unkey-Telemetry-Platform: Vercel" \ + -H "Unkey-Telemetry-Runtime: edge-light" \ + -d '{ "key": "<...>" }' +``` diff --git a/apps/engineering/content/docs/contributing/testing.mdx b/apps/engineering/content/docs/contributing/testing.mdx new file mode 100644 index 0000000000..e1231149a0 --- /dev/null +++ b/apps/engineering/content/docs/contributing/testing.mdx @@ -0,0 +1,28 @@ +--- +title: Testing +description: James loves writing tests +--- + + +We use [vitest](https://vitest.dev/) for our unit and integration tests. You can run the tests with: + +```bash +pnpm install +pnpm test +``` + +## API Tests + +`/apps/api` is our core product and needs to be heavily tested. Unit tests are not enough so we also use integration tests: + +### `integration` + +Full end to end tests require a running API either locally or in a deployed environment. + ```bash + cd apps/api + + UNKEY_BASE_URL= + UNKEY_ROOT_KEY= + pnpm test:integration + ``` + diff --git a/apps/engineering/content/docs/contributing/versions.mdx b/apps/engineering/content/docs/contributing/versions.mdx new file mode 100644 index 0000000000..4f656883c3 --- /dev/null +++ b/apps/engineering/content/docs/contributing/versions.mdx @@ -0,0 +1,43 @@ +--- +title: Versioning +description: "How to release new versions of the repository." +--- +import { Step, Steps } from 'fumadocs-ui/components/steps'; + + +# Repository Version + +The main version of the repository is only for the `agent`. Sdks and other libraries have their own independent versioning. + +## Releasing packages + +All of the npm packages are versioned via changesets. This allows us to have a dedicated version for the agent, while still allowing us to version each package independently. + +To release a new version of a package, you need to create a new changeset with your PR. This will trigger a GitHub action that will publish the new version of the package. + + + + In your feature branch, create a new changeset with `pnpm changeset` + + + + Commit the generated changeset alongside your changes. + Changesets will be generated in the `.changeset` folder in the repository root. + + + + Create a new PR into `main`. + + + + *This step happens automatically in the CI* + + Once the PR is approved and merged, we create a new PR automatically in the CI, which consumes the changesets and bumps the versions accordingly. + + + *This step happens automatically in the CI* + + Merging the version-bump pr will release all the packages to npm if necessary. + + +