From a079bf6fe0f0acc48c68b49c95e8627f9930303d Mon Sep 17 00:00:00 2001 From: Hugo CAILLARD <911307+hugocaillard@users.noreply.github.com> Date: Mon, 12 May 2025 16:29:56 +0200 Subject: [PATCH 1/2] feat: anatomy of a stacks project doc --- .../guides/anatomy-of-a-clarinet-project.mdx | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 content/docs/stacks/clarinet/guides/anatomy-of-a-clarinet-project.mdx diff --git a/content/docs/stacks/clarinet/guides/anatomy-of-a-clarinet-project.mdx b/content/docs/stacks/clarinet/guides/anatomy-of-a-clarinet-project.mdx new file mode 100644 index 000000000..868d198d8 --- /dev/null +++ b/content/docs/stacks/clarinet/guides/anatomy-of-a-clarinet-project.mdx @@ -0,0 +1,126 @@ +--- +title: Anatomy of a Clarinet Project +description: Learn about how a Clarinet project is structured. +--- + +This document provides a detailed overview of the files that need to be present in a Clarinet +project. And how to configure the differents tools being used. Including Clarinet but also other +tools like Vitest, TypeScript, etc. + +## Project Structure + +``` +. +├── Clarinet.toml +├── contracts +│ └── my-contract.clar +├── package.json +├── settings +│ ├── Devnet.toml +│ ├── Mainnet.toml +│ └── Testnet.toml +├── tests +│ └── my-contract.test.ts +├── tsconfig.json +└── vitest.config.js +``` + +## Clarinet.toml + +This is the manifest of the project. It contains the name of the project as well as a few other +properties. + +This is also this file that will list the smart contracts that are part of the project, including +their name and the path to the file. We recommend to always set the `clarity_version` and `epoch` to +the latest. Especially the `epoch`, since you smart contract will eventually be deployed in this +epoch on mainnet. + +```toml +[contracts.my-contract] +path = 'contracts/my-contract.clar' +clarity_version = 3 +epoch = 3.1 +``` + +## package.json + +Because Clarinet relies on Node.js and NPM to write unit tests for your project, there is a +package.json file that will list the dependencies of the project. By defualt, Clarinet comes with +the following dependencies: + +- `@hirosystems/clarinet-sdk`: The Clarinet JS SDK is a version of the Clarinet that is compiled to + Wasm that can run in Node.js. It's used to interact with the Simnet. +- `vitest`: This the testing framework that Clarinet uses to run the tests. Learn more on the + [Vitest website](https://vitest.dev/). +- `@stacks/transactions`: This is the Stacks transactions library that is used to interact with + Clarity values in JavaScript +- `chokidar-cli`: This is a library that is used to watch the files and re-run tests on changes. +- `vitest-environment-clarinet`: this library help bootstrapping the Simnet in the testing + environment. For example, it will initialize the Simnet and makes sure it available globally in + the testing environment. + +As of May 2025, Clarinet 3.0 support the latest version of these dependencies, especially: + +- `vitest` 3.x +- `@stacks/transactions` 7.x + +We recommend to always use the latest version of `@hirosystems/clarinet-sdk` and +`vitest-environment-clarinet`. + +## vitest.config.js + +This is the configuration file for Vitest. Here, we specify some inmportant settings for the testing +framework to work with Clarinet. This is what the default configuration looks like: + +```js +/// + +import { defineConfig } from "vite"; +import { vitestSetupFilePath, getClarinetVitestsArgv } from "@hirosystems/clarinet-sdk/vitest"; + +export default defineConfig({ + test: { + environment: "clarinet", // use vitest-environment-clarinet + pool: "forks", + poolOptions: { + forks: { singleFork: true }, + }, + setupFiles: [ + vitestSetupFilePath, + // custom setup files can be added here + ], + environmentOptions: { + clarinet: { + ...getClarinetVitestsArgv(), + // add or override options + }, + }, + }, +}); +``` + +It export a configuration object with `export default defineConfig({ test: {}})` where we specify +the following options: + +- `environment: "clarinet"`: Tell vitest to use the `vitest-environment-clarinet` environment. +- `pool: "forks"`, now the default value in Vitest 3.x. Tells Vitest to run process in + `child_process`, learn more in [Vitest docs](https://vitest.dev/config/#pool). +- `poolOptions: { forks: { singleFork: true } }`, run all tests in the same process. Thus allowing + efficient re-use of the Simnet and caching. Test isolation is provided by resetting the Simnet for + each test. The `setupFiles` are taking care of it. + +## tsconfig.json + +This is a regular TypeScript configuration file. The `compilerOptions` are customizable to suit your +needs and preferences. + +It's impotant to properly set the `include` property, by default it points to the helpers files +defined the clarinet-sdk package, and to the tests directory. In a monorepo setup with multiple +package, you might need to adjust the path to node_modules. + +```json + "include": [ + "node_modules/@hirosystems/clarinet-sdk/vitest-helpers/src", + "tests" + ] +``` From 2dba166f47e0fa4c8da8574f067564ad61acbb41 Mon Sep 17 00:00:00 2001 From: Ryan Waits Date: Tue, 13 May 2025 08:35:30 -0500 Subject: [PATCH 2/2] minor ui and copy edits --- .../guides/anatomy-of-a-clarinet-project.mdx | 50 ++++++++++--------- 1 file changed, 27 insertions(+), 23 deletions(-) diff --git a/content/docs/stacks/clarinet/guides/anatomy-of-a-clarinet-project.mdx b/content/docs/stacks/clarinet/guides/anatomy-of-a-clarinet-project.mdx index 868d198d8..b382d6e54 100644 --- a/content/docs/stacks/clarinet/guides/anatomy-of-a-clarinet-project.mdx +++ b/content/docs/stacks/clarinet/guides/anatomy-of-a-clarinet-project.mdx @@ -3,27 +3,31 @@ title: Anatomy of a Clarinet Project description: Learn about how a Clarinet project is structured. --- +import { File, Folder, Files } from 'fumadocs-ui/components/files'; + This document provides a detailed overview of the files that need to be present in a Clarinet -project. And how to configure the differents tools being used. Including Clarinet but also other +project. And how to configure the different tools being used. Including Clarinet but also other tools like Vitest, TypeScript, etc. ## Project Structure -``` -. -├── Clarinet.toml -├── contracts -│ └── my-contract.clar -├── package.json -├── settings -│ ├── Devnet.toml -│ ├── Mainnet.toml -│ └── Testnet.toml -├── tests -│ └── my-contract.test.ts -├── tsconfig.json -└── vitest.config.js -``` + + + + + + + + + + + + + + + + + ## Clarinet.toml @@ -45,7 +49,7 @@ epoch = 3.1 ## package.json Because Clarinet relies on Node.js and NPM to write unit tests for your project, there is a -package.json file that will list the dependencies of the project. By defualt, Clarinet comes with +package.json file that will list the dependencies of the project. By default, Clarinet comes with the following dependencies: - `@hirosystems/clarinet-sdk`: The Clarinet JS SDK is a version of the Clarinet that is compiled to @@ -59,7 +63,7 @@ the following dependencies: environment. For example, it will initialize the Simnet and makes sure it available globally in the testing environment. -As of May 2025, Clarinet 3.0 support the latest version of these dependencies, especially: +As of May 2025, Clarinet 3.0 supports the latest version of these dependencies, especially: - `vitest` 3.x - `@stacks/transactions` 7.x @@ -69,7 +73,7 @@ We recommend to always use the latest version of `@hirosystems/clarinet-sdk` and ## vitest.config.js -This is the configuration file for Vitest. Here, we specify some inmportant settings for the testing +This is the configuration file for Vitest. Here, we specify some important settings for the testing framework to work with Clarinet. This is what the default configuration looks like: ```js @@ -99,10 +103,10 @@ export default defineConfig({ }); ``` -It export a configuration object with `export default defineConfig({ test: {}})` where we specify +It exports a configuration object with `export default defineConfig({ test: {}})` where we specify the following options: -- `environment: "clarinet"`: Tell vitest to use the `vitest-environment-clarinet` environment. +- `environment: "clarinet"`: Tells vitest to use the `vitest-environment-clarinet` environment. - `pool: "forks"`, now the default value in Vitest 3.x. Tells Vitest to run process in `child_process`, learn more in [Vitest docs](https://vitest.dev/config/#pool). - `poolOptions: { forks: { singleFork: true } }`, run all tests in the same process. Thus allowing @@ -114,8 +118,8 @@ the following options: This is a regular TypeScript configuration file. The `compilerOptions` are customizable to suit your needs and preferences. -It's impotant to properly set the `include` property, by default it points to the helpers files -defined the clarinet-sdk package, and to the tests directory. In a monorepo setup with multiple +It's important to properly set the `include` property, by default it points to the helpers files +defined in the clarinet-sdk package, and to the tests directory. In a monorepo setup with multiple package, you might need to adjust the path to node_modules. ```json