chore(repo): Add docs about Typedoc + output fixes

.changeset/yummy-days-sit.md

@@ -0,0 +1,2 @@
+---
+---

.typedoc/README.md

@@ -0,0 +1,83 @@
+# Clerk + Typedoc
+
+## Introduction
+
+Together with [`typedoc.config.mjs`](../typedoc.config.mjs) this folder contains all relevant configuration of our [Typedoc](https://typedoc.org/) usage.
+
+Throughout our packages we use JSDoc to annotate public APIs, for example:
+
+```ts
+/**
+ * Accepts an `unknown` value and determines if it's truthy or not.
+ *
+ * @returns {boolean} Returns true for `true`, true, positive numbers. Returns false for `false`, false, 0, negative integers and anything else.
+ */
+export function isTruthy(value: unknown): boolean {
+  // Return if Boolean
+  if (typeof value === `boolean`) {
+    return value;
+  }
+
+  // Default to false
+  return false;
+}
+```
+
+With our Typedoc configuration this will get turned into a file inside `.typedoc/docs` like so:
+
+```md
+Accepts an `unknown` value and determines if it's truthy or not.
+
+## Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `value`   | `unknown` |
+
+## Returns
+
+Returns true for `true`, true, positive numbers. Returns false for `false`, false, 0, negative integers and anything else.
+```
+
+The [tags](https://typedoc.org/documents/Tags.html) are turned into markdown files that [clerk.com/docs](https://clerk.com/docs) can consume.
+
+## Setup
+
+Our Typedoc setup is controlled by the [`typedoc.config.mjs`](../typedoc.config.mjs) configuration file. On a high-level, the goals of the configuration are:
+
+- Consume all SDKs inside `packages`
+  - But define their entrypoints manually
+- Remove as much unwanted content as possible
+  - Therefore any `@hidden`, `@internal`, or undocumented APIs are ignored
+- Generate MDX output that can be directly used inside [clerk-docs](https://github.com/clerk/clerk-docs)
+
+Most of the heavy lifting of generating the MDX output is done through [typedoc-plugin-markdown](https://typedoc-plugin-markdown.org/).
+
+Inside [`custom-theme.mjs`](./custom-theme.mjs) and [`custom-plugin.mjs`](./custom-plugin.mjs) the MDX output is adjusted to our needs. Both `typedoc` and `typedoc-plugin-markdown` offer hooks and extenable classes/themes to customize the output.
+
+The goals of these customizations are:
+
+- Ensure no links are 404
+- Adjust style preferences to match with existing, handwritten content in Clerk's docs
+- Have a stable, predictable, and reasonable folder structure/output inside `.typedoc/docs`
+  - These file paths will be used inside `<Typedoc />` components in [clerk-docs](https://github.com/clerk/clerk-docs)
+- Again, remove unwanted content to have MDX files for docs consumption
+
+## Usage
+
+To generate the Typedoc MDX files inside `.typedoc/docs` run the following script in the root of the repository:
+
+```shell
+pnpm run typedoc:generate
+```
+
+The `.typedoc/docs` folder is inside the `.gitignore` on purpose. Its contents will be pushed to [clerk/generated-typedoc](https://github.com/clerk/generated-typedoc) in CI. You can use it to debug and tweak the output locally before it gets published.
+
+### Adding a package to the Typedoc output
+
+Make sure that the package directory is listed inside [`typedoc.config.mjs`](../typedoc.config.mjs) `config.entryPoints`. Afterwards Typedoc will inspect the `exports` map and `main` key inside `package.json` to determine the entrypoints for the package.
+
+If for some reason this doesn't work, spend time investigating it. If afterwards it still doesn't work, you can add a `typedoc.json` file to the package and define the `entryPoints` there.
+
+> [!IMPORTANT]
+> If you're generating documentation for files/APIs that are not exported/accessible to a user, it's an error. Unless you want to limit the entry points (e.g. a package exports internal functionality) or modify things like the `compilerOptions`, you probably should not define a custom `typedoc.json` file inside a package.

.typedoc/custom-plugin.mjs

@@ -17,10 +17,14 @@ const FILES_WITHOUT_HEADINGS = [
 
 /**
  * An array of tuples where the first element is the file name and the second element is the new path.
+ * Ideally this is a temporary solution until every one of these files are published in production and can be linked to.
  */
 const LINK_REPLACEMENTS = [
   ['clerk-paginated-response', '/docs/references/javascript/types/clerk-paginated-response'],
   ['paginated-resources', '#paginated-resources'],
+  ['session-resource', '/docs/references/javascript/session'],
+  ['signed-in-session-resource', '/docs/references/javascript/session'],
+  ['sign-up-resource', '/docs/references/javascript/sign-up'],
 ];
 
 /**

docs/CONTRIBUTING.md

@@ -13,6 +13,7 @@ Please note we have a [code of conduct](https://github.com/clerk/javascript/blob
     - [Setting up your local environment](#setting-up-your-local-environment)
     - [Documenting your changes](#documenting-your-changes)
     - [Writing tests](#writing-tests)
+    - [Authoring Typedoc information](#authoring-typedoc-information)
   - [Opening a Pull Request](#opening-a-pull-request)
     - [Changesets](#changesets)
     - [Commit messages](#commit-messages)
@@ -110,6 +111,16 @@ While changing a file inside a package, check if e.g. a `<name>.test.ts` file or
 
 If your change can't only be tested by unit tests, you should add/edit an integration test. You can find all necessary information about this in the [integration tests README](../integration/README.md).
 
+### Authoring Typedoc information
+
+As explained in [documenting your changes](#documenting-your-changes), we use JSDoc to annotate our public API surface. We then use [Typedoc](https://typedoc.org/) to autogenerate docs from these comments.
+
+Locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterwards, you can inspect the MDX files inside `.typdoc/docs`.
+
+These files are pushed to [clerk/generated-typedoc](https://github.com/clerk/generated-typedoc) and then used on Clerk's docs. In the docs you can access the files by using a `<Typedoc src="path/to/file" />` component.
+
+So if you find a typo that's inside a Typedoc file, you'll need to edit the source file, [open a PR](#opening-a-pull-request), and get it merged to `main`. You can preview your changes with the aforementioned `pnpm typedoc:generate` command.
+
 ## Opening a Pull Request
 
 1. Search our repository for open or closed [Pull Requests](https://github.com/clerk/javascript/pulls) that relate to your submission. You don't want to duplicate effort.

packages/shared/src/utils/createDeferredPromise.ts

@@ -5,6 +5,7 @@ type Callback = (val?: any) => void;
 /**
  * Create a promise that can be resolved or rejected from
  * outside the Promise constructor callback
+ * @internal
  */
 export const createDeferredPromise = () => {
   let resolve: Callback = noop;

packages/types/src/jwtv2.ts

@@ -116,6 +116,7 @@ export interface JwtPayload extends CustomJwtSessionClaims {
 
 /**
  * JWT Actor - [RFC8693](https://www.rfc-editor.org/rfc/rfc8693.html#name-act-actor-claim).
+ * @inline
  */
 export interface ActClaim {
   sub: string;

packages/types/src/utils.ts

@@ -92,6 +92,7 @@ export type Serializable<T> = {
 /**
  * Enables autocompletion for a union type, while keeping the ability to use any string
  * or type of `T`
+ * @internal
  */
 export type Autocomplete<U extends T, T = string> = U | (T & Record<never, never>);
 

typedoc.config.mjs

@@ -74,7 +74,6 @@ const typedocPluginReplaceTextOptions = {
 /** @type {Partial<import("typedoc").TypeDocOptions>} */
 const config = {
   out: './.typedoc/docs',
-  json: './.typedoc/docs.json',
   entryPointStrategy: 'packages',
   plugin: [
     'typedoc-plugin-replace-text',