From 6536ab714eb57f4cc1ad5a21fffc23b5ff29bc92 Mon Sep 17 00:00:00 2001 From: Pablo Alayeto <55535804+Pabl0cks@users.noreply.github.com> Date: Wed, 21 Aug 2024 03:40:45 +0200 Subject: [PATCH] List of templates and args example files (#97) Co-authored-by: Shiv Bhonde --- contributors/TEMPLATE-FILES.md | 32 +++++++++++++++++++++++++++ contributors/TEMPLATING.md | 2 ++ contributors/THIRD-PARTY-EXTENSION.md | 2 +- 3 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 contributors/TEMPLATE-FILES.md diff --git a/contributors/TEMPLATE-FILES.md b/contributors/TEMPLATE-FILES.md new file mode 100644 index 000000000..2fc34e283 --- /dev/null +++ b/contributors/TEMPLATE-FILES.md @@ -0,0 +1,32 @@ +# Template and Args File List + +This document provides a comprehensive list of `.template.mjs` files and their corresponding `.args.mjs` example files used in the `create-eth` project. + +Template files are the base files that can be extended by third-party extensions. Args files are used to inject additional content into these template files. Understanding the relationship between these files is crucial for developing extensions and customizing the base instance created by `create-eth`. + +If you're interested in developing third-party extensions, the [THIRD-PARTY-EXTENSION.md](./THIRD-PARTY-EXTENSION.md) guide provides detailed instructions on the process. Additionally, we have a [YouTube tutorial](https://www.youtube.com/watch?v=XQCv533XGZk) that walks you through the process of creating an extension step-by-step. + +#### Useful for third-party extensions + +| Template | Example args file | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [(NextJS component) `Header.tsx.template.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/base/packages/nextjs/components/Header.tsx.template.mjs) | [(NextJS component) `Header.tsx.args.mjs`](https://github.com/scaffold-eth/create-eth-extensions/blob/subgraph/extension/packages/nextjs/components/Header.tsx.args.mjs) | +| [(NextJS component) `ScaffoldEthAppWithProviders.tsx.template.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/base/packages/nextjs/components/ScaffoldEthAppWithProviders.tsx.template.mjs) | [(NextJS component) `ScaffoldEthAppWithProviders.tsx.args.mjs`](https://github.com/scaffold-eth/create-eth-extensions/blob/subgraph/extension/packages/nextjs/components/ScaffoldEthAppWithProviders.tsx.args.mjs) | +| [(NextJS app) `layout.tsx.template.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/base/packages/nextjs/app/layout.tsx.template.mjs) | [(NextJS app) `layout.tsx.args.mjs`](https://github.com/scaffold-eth/create-eth-extensions/blob/onchainkit/extension/packages/nextjs/app/layout.tsx.args.mjs) | +| [(NextJS config) `scaffold.config.ts.template.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/base/packages/nextjs/scaffold.config.ts.template.mjs) | [(NextJS config) `scaffold.config.ts.args.mjs`](https://github.com/scaffold-eth/create-eth-extensions/blob/onchainkit/extension/packages/nextjs/scaffold.config.ts.args.mjs) | +| [(NextJS) `.env.example.template.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/base/packages/nextjs/.env.example.template.mjs) | [(NextJS) `.env.example.args.mjs`](https://github.com/scaffold-eth/create-eth-extensions/blob/onchainkit/extension/packages/nextjs/.env.example.args.mjs) | +| [(Foundry script) `Deploy.s.sol.template.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/solidity-frameworks/foundry/packages/foundry/script/Deploy.s.sol.template.mjs) | [(Foundry script) `Deploy.s.sol.args.mjs`](https://github.com/scaffold-eth/create-eth-extensions/blob/erc-20/extension/packages/foundry/script/Deploy.s.sol.args.mjs) | +| [(Root) `README.md.template.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/base/README.md.template.mjs) | [(Root) `README.md.args.mjs`](https://github.com/scaffold-eth/create-eth-extensions/blob/subgraph/extension/README.md.args.mjs) | + +#### create-eth internal use + +| Template | Example args file | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [(GitHub workflow) `lint.yaml.template.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/base/.github/workflows/lint.yaml.template.mjs) | [(GitHub workflow) `lint.yaml.args.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/solidity-frameworks/hardhat/.github/workflows/lint.yaml.args.mjs) | +| [(Nextjs blockExplorer address) `page.tsx.template.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/base/packages/nextjs/app/blockexplorer/address/[address]/page.tsx.template.mjs) | [(BlockExplorer address) `page.tsx.args.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/solidity-frameworks/hardhat/packages/nextjs/app/blockexplorer/address/[address]/page.tsx.args.mjs) | +| [(Foundry) `.env.template.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/solidity-frameworks/foundry/packages/foundry/.env.template.mjs) | we need to create a `.env` file for the foundry to work properly out of box | +| [(Foundry) `deployments/.gitignore.template.mjs`](https://github.com/scaffold-eth/create-eth/blob/main/templates/solidity-frameworks/foundry/packages/foundry/deployments/.gitignore.template.mjs) | this makes sure we have empty `deployments` out of box | + +We also have `.gitignore.template.mjs` files in [root](https://github.com/scaffold-eth/create-eth/blob/main/templates/base/.gitignore.template.mjs), [nextjs](https://github.com/scaffold-eth/create-eth/blob/main/templates/base/packages/nextjs/.gitignore.template.mjs), [hardhat](https://github.com/scaffold-eth/create-eth/blob/main/templates/solidity-frameworks/hardhat/packages/hardhat/.gitignore.template.mjs), [foundry](https://github.com/scaffold-eth/create-eth/blob/main/templates/solidity-frameworks/foundry/packages/foundry/.env.template.mjs) that are used to prevent npm from ignoring the `.gitignore` files in the generated project. + +For more information on how templating works in this project, please refer to the [TEMPLATING.md](./TEMPLATING.md) document. diff --git a/contributors/TEMPLATING.md b/contributors/TEMPLATING.md index c21c90f0e..6a40a8caa 100644 --- a/contributors/TEMPLATING.md +++ b/contributors/TEMPLATING.md @@ -148,6 +148,8 @@ To avoid issues when named arguments have typos, the `withDefaults` utility will For each Template file, we search on the extensions the user selected for the existence of Args files in the exact same relative path. If there are multiple Args files, we combine them into an array +To see the list of template files and their matching args files, check [TEMPLATE-FILES.md](./TEMPLATE-FILES.md). + I've thought about how the strings should be joined, but an option is to use [tagged templates](4). We can go as crazy as we want with tagged templates. # Extension folder anatomy diff --git a/contributors/THIRD-PARTY-EXTENSION.md b/contributors/THIRD-PARTY-EXTENSION.md index 97f51b672..73501ecbd 100644 --- a/contributors/THIRD-PARTY-EXTENSION.md +++ b/contributors/THIRD-PARTY-EXTENSION.md @@ -63,7 +63,7 @@ A developer goes through 2 phases while developing an extension: **Some Caveats:** - Only the addition of new files and new directories is allowed while creating an extension. If you try to overwrite existing files, it won't be reflected. - - `*.args.mjs` files: You might want to add content to existing base instance files. For example, adding a new page link in the Header component. `create-eth` allows injecting additional content into **certain files** with [`*.args.mjs`](TEMPLATING.md#args-files) files. + - `*.args.mjs` files: You might want to add content to existing base instance files. For example, adding a new page link in the Header component. `create-eth` allows injecting additional content into **certain files** with [`*.args.mjs`](TEMPLATING.md#args-files) files. For a list of supported template files and their corresponding args files, see [TEMPLATE-FILES.md](./TEMPLATE-FILES.md). - Changes to `package.json` won't be copied directly; instead, you should manually create/update `package.json` with only things necessary for the extension inside the `create-eth/externalExtensions/${extensionName}` directory. For example, check out this [`package.json`](https://github.com/scaffold-eth/create-eth-extensions/blob/subgraph/extension/packages/nextjs/package.json) from the `subgraph` extension, which adds extra dependencies to the frontend. > TIP: The next section command should guide you with info when changes to unsupported files are detected, or you could inject some content using `*.args.mjs` for the respective file.