From 8626d02d7d6bd66aebf397fe5ffc48106ec8a425 Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Sun, 1 Oct 2023 14:30:36 -0400
Subject: [PATCH] docs(website): mention how rule options should be handled

---
 docs/developers/Custom_Rules.mdx | 52 ++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/docs/developers/Custom_Rules.mdx b/docs/developers/Custom_Rules.mdx
index e64156d1ff4e..b2ca6d64c807 100644
--- a/docs/developers/Custom_Rules.mdx
+++ b/docs/developers/Custom_Rules.mdx
@@ -121,6 +121,58 @@ export const rule = ESLintUtils.RuleCreator.withoutDocs({
 We recommend any custom ESLint rule include a descriptive error message and link to informative documentation.
 :::
 
+## Handling rule options
+
+ESLint rules can take options. When handling options, you will need to add information in at most three places:
+
+- The `Options` generic type argument to `RuleCreator`, where you declare the type of the options
+- The `meta.schema` property, where you add a JSON schema describing the options shape
+- The `defaultOptions` property, where you add the default options value
+
+```ts
+type MessageIds = 'lowercase' | 'uppercase';
+
+type Options = [
+  {
+    preferredCase: 'lower' | 'upper';
+  },
+];
+
+export const rule = createRule<Options, MessageIds>({
+  meta: {
+    // ...
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          preferredCase: {
+            type: 'string',
+            enum: ['lower', 'upper'],
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [
+    {
+      preferredCase: 'lower',
+    },
+  ],
+  create(context, options) {
+    if (options[0].preferredCase === 'lower') {
+      // ...
+    }
+  },
+});
+```
+
+:::warning
+
+When reading the options, use the second parameter of the `create` function, not `context.options` from the first parameter. The first is created by ESLint and does not have the default options applied.
+
+:::
+
 ## AST Extensions
 
 `@typescript-eslint/estree` creates AST nodes for TypeScript syntax with names that begin with `TS`, such as `TSInterfaceDeclaration` and `TSTypeAnnotation`.