remix-docs-gen

About

remix-docs-gen parses all of your Remix loaders and actions and automatically documents all the typings per each route.

Installation

First, you have to install the package itself:

yarn add -D remix-docs-gen

Note that you need @remix-run/server-runtime to be at least ^1.7.0.

Usage Example

You can simply run:

yarn remix-docs-gen -o api-docs.ts

It will magically parse all of your routes and extract all the return types of your loaders and actions.

CLI Options

Option	Alias	Description
--help		Print the help message and exit
--version	-v	Print the CLI version and exit
--output	-o	The path for docs export
--regex	-r	The regex to filter routes
--watch	-w	Watch for changes
--post-export		Execute a command after docs export

Loader output documentation

For example having a route in app/routes/articles with the following content:

export const loader = () => {
  return {
    articles: db.articles.findMany(),
  };
};

The package will fully infer the return type of the loader and produce the following example output:

export interface RemixDocs {
  "/articles": {
    loader: { output: { articles: { id: string; title: string }[] } };
  };
}

Action output documentation

For example having a route in app/routes/articles with the following content:

export const action = () => {
  return {
    myNewArticle: db.articles.create(),
  };
};

The package will fully infer the return type of the action and produce the following example output:

export interface RemixDocs {
  "/articles": {
    action: { output: { myNewArticle: { id: string; title: string } } };
  };
}

Output typings customization

If you'd like to manually define the typings of the loader's or action's output, in your route simply export your custom LoaderOutput or ActionOutput types as needed:

export type LoaderOutput = {
  articles: { custom: string }[];
};

export type ActionOutput = {
  myNewArticle: { custom: string };
};

Which will produce the following result:

export interface RemixDocs {
  "/articles": {
    loader: { output: { articles: { custom: string }[] } };
    action: { output: { myNewArticle: { custom: string } } };
  };
}

Documenting input typings

Besides returing data, loaders and actions usually also expect data to be coming in from the client. To document that, in your route simply export the LoaderInput or ActionInput types as needed:

export type ActionInput = {
  articleData: { title: string };
};

Which will produce the following result:

export interface RemixDocs {
  "/articles": {
    action: { input: { articleData: { title: string } } };
  };
}

This can be very convenient when working with tools like Zod, for example:

const articleSchema = z.object({
  title: z.string().min(1),
});

export type ActionInput = z.infer<typeof articleSchema>;

Route documentation override

If you'd like to fully override the generated documentation typings of a specific route, simply export a Docs type:

export type Docs = {
  my: {
    custom: {
      documentation: string;
    };
  };
};

Which will produce the following output:

export interface RemixDocs {
  "/articles": { my: { custom: { documentation: string } } };
}

Generating typings for specific routes only

You can leverage the --regex or --r flag to only generate typings for the desired routes. For example, that's how you'd document only the routes starting with /api.

yarn remix-docs-gen --output api-docs.ts --regex /api

Dynamic segments

For routes with dynamic segments, the following pattern is being output:

export interface RemixDocs {
  "/reset-password/:token": {
    // ...
  };
}

Generating typings for other languages

For generating typings for other languages besides Typescript, you can use tools like quicktype on top of the generated Typescript file.