This page provides a practical guide for developers working on the AStack codebase, covering common development tasks, package management, and release workflows. It documents the daily commands and procedures used when contributing to or extending AStack.
For information about the monorepo structure itself, see Monorepo Structure. For details on the build system configuration, see Build System and Tooling. For dependency management and versioning concepts, see Dependencies and Versioning.
The monorepo provides development mode for packages that support hot-reloading:
Start all packages in development mode:
This executes turbo run dev package.json14 which runs the dev script in all packages that define it. Individual packages like @astack-tech/integrations use tsup --watch packages/integrations/package.json34 to rebuild on file changes.
Start development for specific packages:
Build all packages:
This runs turbo run build package.json13 which orchestrates builds across the monorepo with dependency awareness. Turbo caches build outputs for faster rebuilds.
Build specific packages:
Package-level builds use tsup packages/integrations/package.json35 to bundle TypeScript into CJS and ESM formats.
Clean build artifacts:
This removes all dist directories and the root node_modules package.json19
Check code style:
Executes eslint against packages/**/*.{ts,tsx} and examples/**/*.{ts,tsx} package.json16
Auto-fix linting issues:
Applies automatic fixes where possible package.json17
Format code:
Runs prettier --write on all TypeScript and Markdown files package.json20
Verify TypeScript types:
Runs tsc --noEmit in all packages via Turbo package.json21 checking types without emitting output.
Run all tests:
Executes turbo run test package.json18 running tests in all packages that define a test script. Individual packages use vitest run packages/integrations/package.json38
Run tests in watch mode (package-level):
Sources: package.json12-21
workspaces pattern package.json9-11:tsup.config.ts following the pattern in existing packages.Install dependencies for all packages:
Add dependency to specific package:
Add workspace dependency:
The workspace:* protocol ensures the package always uses the local version packages/integrations/package.json60
Update all dependencies:
Update specific package:
Sources: package.json12-21 packages/integrations/package.json33-39
AStack uses Changesets for version management and publishing.
When making changes that should trigger a release:
Generate changeset:
This prompts for:
The tool creates a markdown file in .changeset/ .changeset/modern-ducks-drop.md1-6:
Update package versions:
This runs changeset version package.json23 which:
Publish to npm:
Executes turbo run build && changeset publish package.json24 which:
Enter pre-release mode:
Runs changeset pre enter beta package.json25 creating .changeset/pre.json .changeset/pre.json1-15:
Publish beta version:
Executes pnpm build && pnpm -r publish --tag beta --access public package.json27 publishing with the beta tag.
Exit pre-release mode:
Runs changeset pre exit package.json26 removing pre-release configuration.
Publish stable version:
Publishes to the latest tag package.json28
Sources: package.json22-28 .changeset/pre.json1-15 .changeset/modern-ducks-drop.md1-6
| Step | Command | Purpose |
|---|---|---|
| 1 | pnpm install | Ensure dependencies are up to date |
| 2 | pnpm dev | Start development servers |
| 3 | (edit code) | Implement feature |
| 4 | pnpm lint:fix | Fix linting issues |
| 5 | pnpm check-types | Verify TypeScript types |
| 6 | pnpm test | Run test suite |
| 7 | pnpm build | Verify build succeeds |
| 8 | pnpm changeset | Document changes |
| 9 | git commit | Commit with changeset |
| Step | Command | Purpose |
|---|---|---|
| 1 | (write failing test) | Reproduce bug |
| 2 | pnpm test | Confirm test fails |
| 3 | (fix code) | Implement fix |
| 4 | pnpm test | Verify test passes |
| 5 | pnpm lint && pnpm check-types | Quality checks |
| 6 | pnpm changeset | Document patch |
| 7 | git commit | Commit fix |
| Step | Command | Purpose |
|---|---|---|
| 1 | pnpm pre:beta | Enter beta mode |
| 2 | (make changes and add changesets) | Development |
| 3 | pnpm version-packages | Bump to beta versions |
| 4 | git commit -m "Version beta" | Commit version changes |
| 5 | pnpm publish:beta | Publish to npm beta tag |
| 6 | git push --follow-tags | Push changes and tags |
| Step | Command | Purpose |
|---|---|---|
| 1 | pnpm pre:exit | Exit beta mode |
| 2 | pnpm version-packages | Bump to stable versions |
| 3 | git commit -m "Version stable" | Commit version changes |
| 4 | pnpm release | Build and publish |
| 5 | git push --follow-tags | Push changes and tags |
Turbo caches task outputs based on input file hashes. The configuration is in turbo.json at the monorepo root, though the file wasn't provided in the source materials.
Key Turbo behaviors:
Turbo commands used:
turbo run build package.json13turbo run dev package.json14turbo run test package.json18turbo run check-types package.json21turbo run clean package.json19Node.js version:
>=18.0.0 package.json6-8Package manager:
pnpm@10.18.1 package.json37Issue: tsup fails with module resolution errors
Solution:
pnpm cleanpnpm installpnpm buildIssue: Conflicting peer dependencies
Solution: Use pnpm install --force to override peer dependency checks (use cautiously).
Issue: Stale cache causing incorrect builds
Solution:
Issue: Pre-release mode stuck
Solution:
Sources: package.json1-51 packages/integrations/package.json1-63 .changeset/pre.json1-15
Refresh this wiki