From 1a8bc0ca02205964ee5063a7441f17d0064f0815 Mon Sep 17 00:00:00 2001 From: Shiv Bhonde Date: Fri, 10 Jan 2025 14:16:52 +0530 Subject: [PATCH 1/3] 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 `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` + +
+ + + Example `hardhat.config.js.template.mjs` + + + +```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", + }, + }, + }, + }, +}; +``` + +
+ +2. When adding new code/logic: + +- Use descriptive/sensible `string` arguments. Depending on level of customisation. + +
+ + + Example `Component.tsx.template.mjs` + + + +```typescript +export default withDefaults( + ({ preConfigContent, renderContent }) => ` +import { Base } from './Base'; +${preConfigContent} + +export const Component = () => { +${renderContent} +}; +`, + { + preConfigContent: "", + renderContent: "", + }, +); +``` + +
+ ## 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. From 2555dcb146979de490462df2a58b152d06f0091c Mon Sep 17 00:00:00 2001 From: Shiv Bhonde Date: Mon, 13 Jan 2025 14:50:01 +0530 Subject: [PATCH 2/3] update explaination --- contributors/TEMPLATING.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/contributors/TEMPLATING.md b/contributors/TEMPLATING.md index 4aee51394..4a795c09a 100644 --- a/contributors/TEMPLATING.md +++ b/contributors/TEMPLATING.md @@ -185,9 +185,10 @@ This customisation can be broadly broken into: - Use `preConfigContent` (string) for imports and variable declarations - Use `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` +- 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
@@ -202,11 +203,12 @@ 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"], + url: `https://eth-mainnet.g.alchemy.com/v2/\${providerApiKey}`, + accounts: ["$$$deployerPrivateKey"], // ==> accounts: [deployerPrivateKey] }, }, }; @@ -215,6 +217,9 @@ export default withDefaults( ({ preConfigContent, configOverrides }) => ` ${preConfigContent} +const deployerPrivateKey = + process.env.__RUNTIME_DEPLOYER_PRIVATE_KEY ?? "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"; + const config = ${stringify({ ...defaultConfig, ...configOverrides })}; export default config; @@ -235,13 +240,14 @@ export const configOverrides = { networks: { hardhat: { forking: { + enabled: '$$$process.env.MAINNET_FORKING_ENABLED === "false"', // enabled: process.env.MAINNET_FORKING_ENABLED === "false" blockNumber: 1234567, }, }, customNetwork: { url: "https://custom.network", - accounts: ["$$$deployerPrivateKey"], // Use $$$ for template variables - blah: `test ${CUSTOM_API_KEY}`, // Use ${} for preConfigContent variables + accounts: ["$$$deployerPrivateKey"], // accounts: [deployerPrivateKey] + blah: `test \${CUSTOM_API_KEY}`, // blah: `test ${CUSTOM_API_KEY}` verify: { etherscan: { apiUrl: "https://api.custom-explorer.io", From 89359030e77566b9127da8ef07d6eac46c00731c Mon Sep 17 00:00:00 2001 From: Shiv Bhonde Date: Mon, 13 Jan 2025 14:55:03 +0530 Subject: [PATCH 3/3] give names to examples --- contributors/TEMPLATING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/contributors/TEMPLATING.md b/contributors/TEMPLATING.md index 4a795c09a..288075d2c 100644 --- a/contributors/TEMPLATING.md +++ b/contributors/TEMPLATING.md @@ -240,14 +240,14 @@ export const configOverrides = { networks: { hardhat: { forking: { - enabled: '$$$process.env.MAINNET_FORKING_ENABLED === "false"', // enabled: process.env.MAINNET_FORKING_ENABLED === "false" + enabled: '$$$process.env.MAINNET_FORKING_ENABLED === "false"', // (expression) enabled: process.env.MAINNET_FORKING_ENABLED === "false" blockNumber: 1234567, }, }, customNetwork: { url: "https://custom.network", - accounts: ["$$$deployerPrivateKey"], // accounts: [deployerPrivateKey] - blah: `test \${CUSTOM_API_KEY}`, // blah: `test ${CUSTOM_API_KEY}` + 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",