initial draft for template args rules (#195)

contributors/TEMPLATING.md

@@ -176,6 +176,121 @@ 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 defined in template and `preConfigContent` in two ways:
+  - `$$$variableName` - When variable needs to be used without quotes (expressions/variables)
+    - example: `{ accounts: ["$$$deployerPrivateKey"] }` -> `{ accounts: [deployerPrivateKey] }`
+  - `\${variableName}` - When variable needs to be interpolated within a string
+
+<details>
+  <summary>
+
+    Example `hardhat.config.js.template.mjs`
+
+  </summary>
+
+```typescript
+import { withDefaults } from "../utils";
+
+const defaultConfig = {
+  networks: {
+    hardhat: {
+      enabled: '$$$process.env.MAINNET_FORKING_ENABLED === "true"', // enabled: process.env.MAINNET_FORKING_ENABLED === "true"
+      chainId: 31337,
+    },
+    mainnet: {
+      url: `https://eth-mainnet.g.alchemy.com/v2/\${providerApiKey}`,
+      accounts: ["$$$deployerPrivateKey"], // ==> accounts: [deployerPrivateKey]
+    },
+  },
+};
+
+export default withDefaults(
+  ({ preConfigContent, configOverrides }) => `
+${preConfigContent}
+
+const deployerPrivateKey =
+  process.env.__RUNTIME_DEPLOYER_PRIVATE_KEY ?? "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+
+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: {
+        enabled: '$$$process.env.MAINNET_FORKING_ENABLED === "false"', // (expression) enabled: process.env.MAINNET_FORKING_ENABLED === "false"
+        blockNumber: 1234567,
+      },
+    },
+    customNetwork: {
+      url: "https://custom.network",
+      accounts: ["$$$deployerPrivateKey"], // (variable) accounts: [deployerPrivateKey]
+      blah: `test \${CUSTOM_API_KEY}`, // (string interpolation) blah: `test ${CUSTOM_API_KEY}`
+      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.