From 1a8bc0ca02205964ee5063a7441f17d0064f0815 Mon Sep 17 00:00:00 2001
From: Shiv Bhonde <shivbhonde04@gmail.com>
Date: Fri, 10 Jan 2025 14:16:52 +0530
Subject: [PATCH] inital draft for template args rules

---
 contributors/TEMPLATING.md | 109 +++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)

diff --git a/contributors/TEMPLATING.md b/contributors/TEMPLATING.md
index d9f8b5bf0..4aee51394 100644
--- a/contributors/TEMPLATING.md
+++ b/contributors/TEMPLATING.md
@@ -176,6 +176,115 @@ The special files and folders are:
 
 # Things worth mentioning
 
+## Rules for template args:
+
+The reason for converting normal file to template is allowing customisation to that file for extension developer.
+This customisation can be broadly broken into:
+
+1. **When extending/modifying already declared variables/objects**:
+
+- Use `preConfigContent` (string) for imports and variable declarations
+- Use `<name>Override` (object) to extend existing variables/objects
+- Can reference variables in two ways:
+  - `$$$variableName` - For variables already defined in template
+  - `${variableName}` - For variables defined in your `preConfigContent`
+
+<details>
+  <summary>
+
+    Example `hardhat.config.js.template.mjs`
+
+  </summary>
+
+```typescript
+import { withDefaults } from "../utils";
+
+const defaultConfig = {
+  networks: {
+    hardhat: {
+      chainId: 31337,
+    },
+    mainnet: {
+      url: `https://eth-mainnet.g.alchemy.com/v2/$$$providerApiKey`,
+      accounts: ["$$$deployerPrivateKey"],
+    },
+  },
+};
+
+export default withDefaults(
+  ({ preConfigContent, configOverrides }) => `
+${preConfigContent}
+
+const config = ${stringify({ ...defaultConfig, ...configOverrides })};
+
+export default config;
+`,
+  {
+    preConfigContent: "",
+    configOverrides: {},
+  },
+);
+
+// In extension's args file (hardhat.config.ts.args.mjs)
+export const preConfigContent = `
+// Custom variables
+const CUSTOM_API_KEY = process.env.CUSTOM_API_KEY;
+`;
+
+export const configOverrides = {
+  networks: {
+    hardhat: {
+      forking: {
+        blockNumber: 1234567,
+      },
+    },
+    customNetwork: {
+      url: "https://custom.network",
+      accounts: ["$$$deployerPrivateKey"], // Use $$$ for template variables
+      blah: `test ${CUSTOM_API_KEY}`, // Use ${} for preConfigContent variables
+      verify: {
+        etherscan: {
+          apiUrl: "https://api.custom-explorer.io",
+          apiKey: "$$$etherscanApiKey",
+        },
+      },
+    },
+  },
+};
+```
+
+</details>
+
+2. When adding new code/logic:
+
+- Use descriptive/sensible `string` arguments. Depending on level of customisation.
+
+<details>
+  <summary>
+
+    Example `Component.tsx.template.mjs`
+
+  </summary>
+
+```typescript
+export default withDefaults(
+  ({ preConfigContent, renderContent }) => `
+import { Base } from './Base';
+${preConfigContent}
+
+export const Component = () => {
+${renderContent}
+};
+`,
+  {
+    preConfigContent: "",
+    renderContent: "",
+  },
+);
+```
+
+</details>
+
 ## Recommended way to handle complex arguments in templates
 
 Most of the time you will use string arguments for templating, but sometimes you will need to add arrays, objects, bigints, etc. You can handle them however you want, but we're recommending to use the table below as a helper.