|
| 1 | +# TypeScript Documentation Examples |
| 2 | + |
| 3 | +This directory contains TypeScript examples used in the Aztec documentation. Each example is a self-contained project that demonstrates specific Aztec.js functionality. |
| 4 | + |
| 5 | +## Directory Structure |
| 6 | + |
| 7 | +Each example directory contains: |
| 8 | +- `index.ts` - The example code with `docs:start:` and `docs:end:` markers for inclusion in documentation |
| 9 | +- `config.yaml` - Specifies dependencies and any custom contract artifacts needed |
| 10 | +- `yarn.lock` - Empty file to prevent yarn from using parent monorepo's yarn.lock |
| 11 | + |
| 12 | +## Validation: Type Checking |
| 13 | + |
| 14 | +The `bootstrap.sh` script validates all examples by: |
| 15 | + |
| 16 | +1. Reading `config.yaml` to determine dependencies and custom contracts |
| 17 | +2. Running codegen for any custom contracts specified (from `docs/target/`) |
| 18 | +3. Installing linked `@aztec/*` dependencies from `yarn-project/` |
| 19 | +4. Running `tsc --noEmit` to type-check the example |
| 20 | + |
| 21 | +Run validation for all examples: |
| 22 | +```bash |
| 23 | +./bootstrap.sh |
| 24 | +``` |
| 25 | + |
| 26 | +Run validation for specific example(s): |
| 27 | +```bash |
| 28 | +./bootstrap.sh aztecjs_connection aztecjs_advanced |
| 29 | +``` |
| 30 | + |
| 31 | +## Execution: Test Runner |
| 32 | + |
| 33 | +The `aztecjs_runner/run.sh` script executes examples against a live local Aztec network to verify they work correctly. |
| 34 | + |
| 35 | +### CI Execution (Docker Compose) |
| 36 | + |
| 37 | +In CI, examples run via `docker-compose.yml` which spins up an Anvil fork, a local Aztec network, and runs the examples automatically. This is triggered by `docs/examples/bootstrap.sh execute` (called from `docs/bootstrap.sh ci`). |
| 38 | + |
| 39 | +```bash |
| 40 | +# Run via bootstrap (recommended for CI) |
| 41 | +cd docs/examples && ./bootstrap.sh execute |
| 42 | + |
| 43 | +# Or invoke docker-compose directly |
| 44 | +cd docs/examples/ts && run_compose_test docs_examples docs-examples . |
| 45 | +``` |
| 46 | + |
| 47 | +### Local Execution |
| 48 | + |
| 49 | +For local development, start the sandbox manually and run examples directly. |
| 50 | + |
| 51 | +#### Prerequisites |
| 52 | + |
| 53 | +- Local Aztec network running (default: `localhost:8080`) |
| 54 | +- Built yarn-project packages |
| 55 | + |
| 56 | +#### Usage |
| 57 | + |
| 58 | +Run all examples: |
| 59 | +```bash |
| 60 | +cd aztecjs_runner |
| 61 | +./run.sh |
| 62 | +``` |
| 63 | + |
| 64 | +Run specific example(s): |
| 65 | +```bash |
| 66 | +./run.sh connection # aztecjs_connection |
| 67 | +./run.sh getting_started # aztecjs_getting_started |
| 68 | +./run.sh advanced authwit # multiple examples |
| 69 | +``` |
| 70 | + |
| 71 | +#### Environment Variables |
| 72 | + |
| 73 | +| Variable | Description | Default | |
| 74 | +|----------|-------------|---------| |
| 75 | +| `AZTEC_NODE_URL` | URL of the Aztec node to connect to | `http://localhost:8080` | |
| 76 | + |
| 77 | +The `AZTEC_NODE_URL` env var is used by both the runner script and the example `index.ts` files. In Docker Compose, it is set to `http://local-network:8080` to point at the compose network's Aztec node. |
| 78 | + |
| 79 | +### Currently Tested Examples |
| 80 | + |
| 81 | +| Example | Description | |
| 82 | +|---------|-------------| |
| 83 | +| `aztecjs_connection` | Basic network connection, account setup, token deployment | |
| 84 | +| `aztecjs_getting_started` | Complete getting started tutorial flow | |
| 85 | +| `aztecjs_advanced` | NO_WAIT transactions, BatchCall, sponsored FPC, events | |
| 86 | +| `aztecjs_authwit` | Authentication witnesses for delegated actions | |
| 87 | +| `aztecjs_testing` | Test patterns: minting, transfers, revert testing | |
| 88 | + |
| 89 | +### Examples Not Executed (Type-Checked Only) |
| 90 | + |
| 91 | +These examples require additional infrastructure or custom contracts with verification keys: |
| 92 | + |
| 93 | +| Example | Reason | |
| 94 | +|---------|--------| |
| 95 | +| `bob_token_contract` | Custom contract requires verification keys | |
| 96 | +| `token_bridge` | Requires L1 contracts and bridge infrastructure | |
| 97 | +| `recursive_verification` | Requires prover and verification key generation | |
| 98 | + |
| 99 | +## Adding New Examples |
| 100 | + |
| 101 | +1. Create a new directory with your example name |
| 102 | +2. Add `index.ts` with your example code |
| 103 | +3. Add `config.yaml` specifying dependencies: |
| 104 | + |
| 105 | +```yaml |
| 106 | +# For examples using pre-built contracts from @aztec/noir-contracts.js |
| 107 | +contracts: [] |
| 108 | + |
| 109 | +dependencies: |
| 110 | + - "@aztec/aztec.js" |
| 111 | + - "@aztec/accounts" |
| 112 | + - "@aztec/test-wallet" |
| 113 | + - "@aztec/noir-contracts.js" |
| 114 | +``` |
| 115 | +
|
| 116 | +4. Create empty `yarn.lock` file |
| 117 | +5. Run `./bootstrap.sh your_example_name` to validate |
| 118 | +6. If the example can run against a live network, add it to `aztecjs_runner/run.sh` |
| 119 | + |
| 120 | +## File Management |
| 121 | + |
| 122 | +The validation and runner scripts generate temporary files during execution. These are cleaned up automatically, but if you need to manually clean: |
| 123 | + |
| 124 | +```bash |
| 125 | +# In each example directory |
| 126 | +rm -rf node_modules .yarn artifacts package.json tsconfig.json .yarnrc.yml |
| 127 | +rm -f .editorconfig .gitattributes .gitignore README.md codegenCache.json |
| 128 | +> yarn.lock # Keep empty |
| 129 | +``` |
0 commit comments