Skip to content

Commit 3bb0617

Browse files
holgerd77acolytec3
holgerd77
and
acolytec3
authored
Consolidate and Update Developer Docs (#4079)
* Move hidden and not-content-matching config/README.md file to root, rename to DEVELOPER.md * Integrate workflow section into new dev docs, reference dev docs from main README * Consolidate testing content * Remove redundant linking content * Remove redundant small configuration guide section * Move over windows users note * Integrate scripts overview * Add references to additional docs * Add additional spellcheck docs section * Some additional tool linking * Minor * cleanup * spellcheck --------- Co-authored-by: acolytec3 <[email protected]>
1 parent d0ff5b8 commit 3bb0617

File tree

3 files changed

+247
-251
lines changed

3 files changed

+247
-251
lines changed

‎DEVELOPER.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
# EthereumJS - Developer Docs
2+
3+
This guide provides an overview of the monorepo, development tools used, shared configuration and additionally covers some advanced topics.
4+
5+
It is intended to be both an entrypoint for external contributors as well as a reference point for team members.
6+
7+
## Contents
8+
9+
- [Monorepo](#monorepo)
10+
- [Structure](#structure)
11+
- [Workflow](#workflow)
12+
- [Development Tools](#development-tools)
13+
- [TypeScript](#typescript)
14+
- [Linting](#linting)
15+
- [Spellcheck](#spellcheck)
16+
- [Testing](#testing)
17+
- [Documentation](#documentation)V
18+
- [Advanced Topics](#advanced-topics)
19+
- [E2E Testing](#e2e-testing)
20+
- [Cross-Package Development](#cross-package-development)
21+
- [Additional Docs](#additional-docs)
22+
- [VM](#vm)
23+
- [Client](#client)
24+
25+
## Monorepo
26+
27+
### Structure
28+
29+
The EthereumJS project uses [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces) to manage all the packages in our monorepo and link packages together.
30+
31+
#### Key Directories
32+
33+
- `/packages` - Contains all EthereumJS packages
34+
- `/config` - Shared configuration files and scripts
35+
- `packages/ethereum-tests` - Git submodule with Ethereum test vectors
36+
37+
### Scripts
38+
39+
The `./config/cli` directory contains helper scripts referenced in package.json files:
40+
41+
- `coverage.sh` - Runs test coverage
42+
- `ts-build.sh` - Builds TypeScript for production
43+
- `ts-compile.sh` - Compiles TypeScript for development
44+
45+
### Workflow
46+
47+
#### Common Commands
48+
49+
- **Clean the workspace**: `npm run clean` - Removes build artifacts and node_modules
50+
- **Lint code**: `npm run lint` - Check code style with ESLint v9 and Biome
51+
- **Fix linting issues**: `npm run lint:fix` - Automatically fix style issues
52+
- **Build all packages**: `npm run build --workspaces` - Build all packages in the monorepo
53+
- **Build documentation**: `npm run docs:build` - Generate documentation for all packages
54+
55+
#### Working on a Specific Package
56+
57+
To focus on a single package (e.g., VM):
58+
59+
1. Navigate to the package directory: `cd packages/vm`
60+
2. Run tests: `npm run test`
61+
3. Run a specific test: `npx vitest test/path/to/test.spec.ts`
62+
4. Build just that package: `npm run build --workspace=@ethereumjs/vm`
63+
64+
#### Cross-Package Development
65+
66+
All packages include a `typescript` entry in the exports map that allows direct use of TypeScript sources without recompilation:
67+
68+
- Run tests with TypeScript sources: `npx vitest --config ../../config/vitest.config.mts test/myTest.spec.ts`
69+
- Run TypeScript scripts: `tsx --conditions=typescript myScript.ts`
70+
- Set environment variable for bash scripts: `NODE_OPTIONS='--conditions=typescript' (if running Node 22+)`
71+
72+
#### Windows Users Note
73+
74+
Windows users might encounter errors with script paths. To fix, configure Git bash as the script shell:
75+
76+
```sh
77+
npm config set script-shell "C:\\Program Files (x86)\\git\\bin\\bash.exe"
78+
```
79+
80+
To reset this setting:
81+
82+
```sh
83+
npm config delete script-shell
84+
```
85+
86+
## Development Tools
87+
88+
### TypeScript
89+
90+
All packages use [TypeScript](https://www.typescriptlang.org/) with a shared base configuration.
91+
92+
#### Configuration Files
93+
94+
Each package should have:
95+
96+
- `tsconfig.json` - For development and testing
97+
- `tsconfig.prod.json` - For building production releases
98+
99+
Example `tsconfig.json`:
100+
```json
101+
{
102+
"extends": "../../config/tsconfig.json",
103+
"include": ["src/**/*.ts", "test/**/*.ts"]
104+
}
105+
```
106+
107+
Example `tsconfig.prod.json`:
108+
```json
109+
{
110+
"extends": "../../config/tsconfig.prod.json",
111+
"include": ["src/**/*.ts"],
112+
"compilerOptions": {
113+
"outDir": "./dist"
114+
}
115+
}
116+
```
117+
118+
#### Build Commands
119+
120+
Use these commands in your package scripts:
121+
122+
```json
123+
{
124+
"scripts": {
125+
"tsc": "../../config/cli/ts-compile.sh",
126+
"build": "../../config/cli/ts-build.sh"
127+
}
128+
}
129+
```
130+
131+
### Linting
132+
133+
We use [ESLint](https://eslint.org/) v9 and [Biome](https://biomejs.dev/) for code style enforcement and linting.
134+
135+
#### Configuration Files
136+
137+
Each package includes:
138+
139+
- `eslint.config.mjs` - package specific ESLint configuration that extends the repository wide config
140+
141+
142+
#### Commands
143+
144+
Commands area available on both root and package levels.
145+
146+
Run `npm run lint` to find lint issues and `npm run lint:fix` to fix fixable lint issues.
147+
148+
149+
### Spellcheck
150+
151+
We use [cspell](https://github.com/streetsidesoftware/cspell) to do spellchecking.
152+
153+
#### Configuration Files
154+
155+
The following two configuration files include a list of allowed words (add yours if you have one necessary) as well as some additional configuration, separate for docs and code.
156+
157+
- `config/cspell-md.json` | `Markdown`
158+
- `config/cspell-ts.json` | `TypeScript`
159+
160+
#### Commands
161+
162+
Commands area available on both root and package levels.
163+
164+
```json
165+
{
166+
"scripts": {
167+
"sc": "npm run spellcheck",
168+
"spellcheck": "npm run spellcheck:ts && npm run spellcheck:md",
169+
"spellcheck:ts": "npx cspell --gitignore -c ../../config/cspell-ts.json ...",
170+
"spellcheck:md": "npx cspell --gitignore -c ../../config/cspell-md.json ..."
171+
}
172+
}
173+
```
174+
175+
### Testing
176+
177+
The project uses [Vitest](https://vitest.dev/) for testing with [c8](https://vitest.dev/guide/coverage.html) for code coverage.
178+
179+
#### General
180+
181+
Each package includes one or more test scripts. To run all tests in any package, use `npm run test`. Refer to the package.json for more specifics.
182+
183+
To run a specific test and watch for changes:
184+
185+
```sh
186+
npx vitest test/path/to/test.spec.ts
187+
```
188+
189+
#### Browser
190+
191+
We use `vitest` with [playwright](https://playwright.dev/) to run browser tests. When running browser tests with `npm run test:browser`, ensure you have a version of the Chromium browser installed. If not, you can run `npx playwright install --with-deps` to install a supported version.
192+
193+
## Advanced Topics
194+
195+
### Linking to an External Library
196+
197+
#### Quick Summary
198+
199+
To test packages with an external project locally, use npm link:
200+
201+
1. Build the package you want to test:
202+
```sh
203+
cd packages/package-name
204+
npm run build
205+
```
206+
207+
2. Link the package globally:
208+
```sh
209+
npm link
210+
```
211+
212+
3. In your test project, link to the local package:
213+
```sh
214+
cd path/to/your/project
215+
npm link @ethereumjs/package-name
216+
```
217+
218+
4. When you make changes to your package, rebuild it for the changes to be reflected.
219+
220+
5. When done testing, unlink:
221+
```sh
222+
# In your test project
223+
npm unlink --no-save @ethereumjs/package-name
224+
225+
# In the package directory
226+
npm unlink
227+
```
228+
229+
When making changes to the linked package, rebuild it for the changes to be reflected in your test project.
230+
231+
### Shared Dependencies
232+
233+
Common development dependencies (e.g. `eslint`, `biome`) are defined in the root `package.json`.
234+
235+
## Additional Docs
236+
237+
There are selected additional developer docs available to get more deep on certain topics. The following is an overview.
238+
239+
### VM
240+
241+
[VM Docs](./packages/vm/DEVELOPER.md) for testing, debugging and VM/EVM profiling.
242+
243+
### Client
244+
245+
[Client Docs](./packages/client/DEVELOPER.md) for running Hive tests.

‎README.md‎

Lines changed: 2 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -78,94 +78,9 @@ git submodule update
7878
npm install
7979
```
8080

81-
### Development Workflow
81+
### Development
8282

83-
The monorepo uses [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces) to link local packages together, making development easier.
84-
85-
#### Common Commands
86-
87-
- **Clean the workspace**: `npm run clean` - Removes build artifacts and node_modules
88-
- **Lint code**: `npm run lint --workspaces` - Check code style with ESLint v9 and Biome
89-
- **Fix linting issues**: `npm run lint:fix --workspaces` - Automatically fix style issues
90-
- **Build all packages**: `npm run build --workspaces` - Build all packages in the monorepo
91-
- **Build documentation**: `npm run docs:build --workspaces` - Generate documentation for all packages
92-
93-
#### Working on a Specific Package
94-
95-
To focus on a single package (e.g., VM):
96-
97-
1. Navigate to the package directory: `cd packages/vm`
98-
2. Run tests: `npm test`
99-
3. Run a specific test: `npx vitest test/path/to/test.spec.ts`
100-
4. Build just that package: `npm run build --workspace=@ethereumjs/vm`
101-
102-
#### Cross-Package Development
103-
104-
All packages include a `typescript` entry in the exports map that allows direct use of TypeScript sources without recompilation:
105-
106-
- Run tests with TypeScript sources: `npx vitest --config ../../config/vitest.config.mts test/myTest.spec.ts`
107-
- Run TypeScript scripts: `tsx --conditions=typescript myScript.ts`
108-
- Set environment variable for bash scripts: `NODE_OPTIONS='--conditions=typescript'`
109-
110-
### Browser Testing
111-
112-
We use `vitest` with `playwright` to run browser tests. When running browser tests with `npm run test:browser`, ensure you have a version of the Chromium browser installed. If not, you can run `npx playwright install --with-deps` to install a supported version.
113-
114-
### Testing Packages with an external project
115-
116-
To test changes locally before publishing, use npm link:
117-
118-
1. **Build the package you want to test**:
119-
120-
```sh
121-
cd packages/vm # Or another package
122-
npm run build
123-
```
124-
125-
2. **Link the package globally**:
126-
127-
```sh
128-
npm link
129-
```
130-
131-
3. **In your test project, link to the local package**:
132-
133-
```sh
134-
cd path/to/your/project
135-
npm link @ethereumjs/vm # Use the appropriate package name
136-
```
137-
138-
4. **When you're done, unlink the package**:
139-
140-
```sh
141-
# In your test project
142-
npm unlink @ethereumjs/vm
143-
144-
# In the package directory
145-
npm unlink
146-
```
147-
148-
When making changes to the linked package, rebuild it for the changes to be reflected in your test project.
149-
150-
### Windows Users Note
151-
152-
Windows users might encounter errors with script paths. To fix, configure Git bash as the script shell:
153-
154-
```sh
155-
npm config set script-shell "C:\\Program Files (x86)\\git\\bin\\bash.exe"
156-
```
157-
158-
To reset this setting:
159-
160-
```sh
161-
npm config delete script-shell
162-
```
163-
164-
### Configuration Guide
165-
166-
The [config](config/) folder gives an overview on shared configuration and scripts between packages.
167-
168-
You can find more detailed information on the configuration of different tooling and language parts (TypeScript, linting, testing,...) in the specific [Configuration Guide](./config/README.md).
83+
See our [Development docs](./DEVELOPER.md) for an overview on things like tooling or configuration if you want to contribute to the EthereumJS monorepo. 🙂
16984

17085
## Branches
17186

0 commit comments

Comments
 (0)