From 999a10148498464328713fc05f82873b9189cce6 Mon Sep 17 00:00:00 2001 From: imrishabh18 Date: Tue, 18 Nov 2025 00:51:12 +0530 Subject: [PATCH 1/2] add the doc for using local packages in development with yalc --- docs/advanced/local-package-development.mdx | 147 ++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/advanced/local-package-development.mdx diff --git a/docs/advanced/local-package-development.mdx b/docs/advanced/local-package-development.mdx new file mode 100644 index 0000000..9b12952 --- /dev/null +++ b/docs/advanced/local-package-development.mdx @@ -0,0 +1,147 @@ +--- +title: Local Package Development +description: Learn how to develop and test local packages with tsci dev using yalc and other linking tools +--- + +## Overview + +When developing tscircuit projects, you may want to test changes to local packages without publishing them to npm. The `tsci dev` command automatically detects and uploads local packages, making local development seamless. + +Currently supported methods: +- **yalc** - Recommended for most use cases +- More linking methods (like `bun link`) coming soon! + +## What is Yalc? + +[Yalc](https://github.com/wclr/yalc) is a tool for managing local package dependencies. It's a better alternative to `npm link` that creates a local package store and symlinks packages into your project's `node_modules`. + +## Installation + +First, install yalc globally: + +```bash +npm install -g yalc +# or +bun install -g yalc +``` + +## Basic Workflow + +### 1. Publish Your Local Package + +In the package you're developing `@/` (e.g., `@tscircuit/pico`): + +```bash +cd path/to/your/local/package +yalc publish +``` + +This publishes the package to your local yalc store. + +### 2. Link the Package to Your Project + +In your tscircuit project: + +```bash +cd path/to/your/tscircuit-project +yalc add @tscircuit/pico +``` + +This will: +- Add the package to your `node_modules` +- Update your `package.json` with a `file:.yalc/@tscircuit/pico` reference +- Create a `.yalc` directory with the package contents + +### 3. Start Development + +Run the dev server as usual: + +```bash +tsci dev index.circuit.tsx +``` + +The dev server will automatically detect that `@tscircuit/pico` is a local package (via the `file:.yalc/` reference) and upload it along with your component files. + +### 4. Update Your Local Package + +When you make changes to your local package: + +```bash +# In the local package directory +yalc push +``` + +This will update all linked projects. You may need to restart `tsci dev` to pick up the changes. + +## How It Works + +The `tsci dev` command automatically uploads packages from `node_modules` **only if** they meet these criteria: + +1. The package is referenced in `package.json` with a `file:.yalc/` path +2. The package exists in your `node_modules` directory + +Regular npm packages (like `react`, `lodash`, etc.) are **not** uploaded to keep bundle sizes small and development fast. + +## Example + +Here's a complete example of developing a custom component library: + +**Your local library** (`my-components`): +```tsx +// my-components/src/index.ts +export const MyCustomChip = (props: any) => { + return +} +``` + +**Publish it locally**: +```bash +cd my-components +yalc publish +``` + +**Use it in your project**: +```bash +cd my-tscircuit-project +yalc add my-components +``` + +**Your component**: +```tsx +// circuit.tsx +import { MyCustomChip } from "my-components" + +export default () => ( + + + +) +``` + +**Start dev server**: +```bash +tsci dev circuit.tsx +``` + +Now both your component and the `my-components` package code will be uploaded to the dev server! + +## Removing Yalc Packages + +To remove a yalc package and restore the npm version: + +```bash +yalc remove @tscircuit/pico +npm install @tscircuit/pico +``` + +Or remove all yalc packages: + +```bash +yalc remove --all +``` + +## Tips + +- Use `yalc push` instead of `yalc publish` when updating packages - it's faster and automatically updates linked projects +- The `.yalc` directory and `yalc.lock` file should be added to `.gitignore` +- Remember to test with the published npm version before releasing to ensure compatibility From 4161a3836aa07287824b3630a81dd0f0a8a62558 Mon Sep 17 00:00:00 2001 From: imrishabh18 Date: Tue, 18 Nov 2025 00:57:55 +0530 Subject: [PATCH 2/2] add the build step --- docs/advanced/local-package-development.mdx | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/advanced/local-package-development.mdx b/docs/advanced/local-package-development.mdx index 9b12952..667b2e0 100644 --- a/docs/advanced/local-package-development.mdx +++ b/docs/advanced/local-package-development.mdx @@ -27,16 +27,24 @@ bun install -g yalc ## Basic Workflow -### 1. Publish Your Local Package +### 1. Build and Publish Your Local Package In the package you're developing `@/` (e.g., `@tscircuit/pico`): ```bash cd path/to/your/local/package + +# Build the package first +bun run build +# or npm run build + +# Then publish to yalc yalc publish ``` -This publishes the package to your local yalc store. +This builds the package and publishes the distribution files to your local yalc store. + +**Note**: You must build the package before publishing with yalc, as it publishes the compiled output (typically in `dist/` or `lib/`), not the source files. ### 2. Link the Package to Your Project @@ -68,10 +76,11 @@ When you make changes to your local package: ```bash # In the local package directory -yalc push +bun run build # Rebuild with your changes +yalc push # Push updates to all linked projects ``` -This will update all linked projects. You may need to restart `tsci dev` to pick up the changes. +This will rebuild and update all linked projects. You may need to restart `tsci dev` to pick up the changes. ## How It Works @@ -96,7 +105,7 @@ export const MyCustomChip = (props: any) => { **Publish it locally**: ```bash -cd my-components +bun run build yalc publish ```