Add generate:watch command move generated specs back into gitignore (#240)

* style: add pnpm-lock.yaml to prettierignore

* build: create generate:watch command

* refactor: capture input/output dirs in variable for openapi generate

* refactor: move build dir to fern dir and add it back to gitignore

* refactor: clean up code related to deprecated build dir

* fix: update fern check PR GH action to generate specs first

* docs: update readme and contrbuting to reflect new project structure

* refactor: rename sandbox-metadata to just metadata

---------

Co-authored-by: dslovinsky <dslovinsky@users.noreply.github.com>

Author: dslovinsky

.gitattributes

@@ -1,4 +1,2 @@
 # Mark generated API specs as generated files
-build/**/*.json linguist-generated=true
-
 fern/dist/** linguist-generated=true

.github/actions/publish-fern/action.yml

@@ -27,15 +27,12 @@ outputs:
 runs:
   using: "composite"
   steps:
-    - name: Install pnpm
-      uses: pnpm/action-setup@v4
-      with:
-        version: 10.9.0
-        run_install: false
+    - name: Setup pnpm
+      uses: ./.github/actions/setup-pnpm
 
-    - name: Install Fern
+    - name: Generate API Specs
       shell: bash
-      run: pnpm install -g fern-api
+      run: pnpm run generate
 
     - name: Build custom app
       shell: bash
@@ -60,9 +57,9 @@ runs:
         FERN_TOKEN: ${{ inputs.fern-token }}
       run: |
         if [[ "${{ inputs.preview }}" == "true" ]]; then
-          OUTPUT=$(fern generate --docs --preview 2>&1) || true
+          OUTPUT=$(pnpm fern generate --docs --preview 2>&1) || true
         else
-          OUTPUT=$(fern generate --docs --log-level debug 2>&1) || true
+          OUTPUT=$(pnpm fern generate --docs --log-level debug 2>&1) || true
         fi
         echo "$OUTPUT"
         URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')

.github/actions/setup-pnpm/action.yml

@@ -8,7 +8,7 @@ runs:
       uses: pnpm/action-setup@v4
       id: pnpm-install
       with:
-        version: 9
+        version: 10.9.0
         run_install: false
 
     - name: Get pnpm store directory

.github/workflows/gh-pages-deploy.yml

@@ -26,13 +26,13 @@ jobs:
 
       - name: Run build script
         id: build
-        run: pnpm generate && pnpm generate:sandbox-metadata
+        run: pnpm generate && pnpm generate:metadata
 
       - name: Upload static files as artifact
         id: deploy-artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: build/
+          path: fern/api-specs/
 
   deploy:
     runs-on: ubuntu-latest

.github/workflows/pr-validation.yml

@@ -45,9 +45,11 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+      - name: Setup pnpm
+        uses: ./.github/actions/setup-pnpm
 
-      - name: Install Fern
-        run: npm install -g fern-api
+      - name: Generate API Specs
+        run: pnpm run generate
 
       - name: Check API is valid
-        run: fern check
+        run: pnpm fern check

.gitignore

@@ -12,9 +12,7 @@ node_modules/
 .eslintcache
 
 # dotenv environment variables file
-.env
-.env.test
-.env*.local
+.env*
 
 # misc
 .DS_Store
@@ -32,4 +30,4 @@ yarn.lock
 debug.log
 
 # generated
-.sandbox-metadata.json
+fern/api-specs/

.lintstagedrc.mjs

@@ -6,6 +6,5 @@ export default {
     "eslint --fix",
     "prettier --write --log-level silent",
   ],
-  "*.{yml,yaml}": ["pnpm run generate", "prettier --write --log-level silent"],
-  "*.json": ["prettier --write --log-level silent"],
+  "*.{yml,yaml,json}": ["prettier --write --log-level silent"],
 };

.prettierignore

@@ -1,5 +1,6 @@
-build/
 # Prettier doesn't support MDX 3 yet
 # https://github.com/prettier/prettier/issues/12209
 **/*.mdx
 **/*.md
+fern/api-specs/
+pnpm-lock.yaml

CONTRIBUTING.md

@@ -27,7 +27,9 @@ Thank you for your interest in contributing to Alchemy's documentation! This gui
 
 * Location: `src/openapi/`
 * Define APIs using YAML following the [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
-* **Tip**: Use the [Redocly VSCode extension](https://marketplace.visualstudio.com/items?itemName=Redocly.openapi-vs-code) to enable OpenAPI spec validation with Intellisense.
+
+> \[!TIP]
+> Use the [Redocly VSCode extension](https://marketplace.visualstudio.com/items?itemName=Redocly.openapi-vs-code) to enable OpenAPI spec validation with Intellisense.
 
 **JSON-RPC APIs (OpenRPC)**
 
@@ -37,17 +39,23 @@ Thank you for your interest in contributing to Alchemy's documentation! This gui
   * `alchemy/`: Alchemy-specific APIs
   * `chains/`: Chain-specific APIs (e.g., ethereum, polygon)
 
+> \[!TIP]
+> Use the [YAML VSCode extension](https://marketplace.cursorapi.com/items?itemName=redhat.vscode-yaml) to get some basic OpenRPC validation with Intellisense.
+
 ### Account Kit Documentation
 
-Account Kit documentation is maintained in the [aa-sdk repository](https://github.com/alchemyplatform/aa-sdk). See its [README](https://github.com/alchemyplatform/aa-sdk/blob/main/docs/README.md) for contribution guidelines.
+Account Kit documentation is maintained separately in the [aa-sdk repository](https://github.com/alchemyplatform/aa-sdk). See its [README](https://github.com/alchemyplatform/aa-sdk/blob/main/docs/README.md) for contribution guidelines.
 
 ## Making Changes
 
-1. Make your changes
-2. Test locally using `pnpm dev`
-3. Commit your changes
-4. Push to your fork
-5. Create a pull request to the upstream
+If you are not an [Alchemy Employee](#alchemy-employees), you will need to create your own fork.
+
+1. Fork the repo (if you haven't already)
+2. Make your changes
+3. Test locally using `pnpm dev`
+4. Commit your changes
+5. Push to your fork
+6. Create a pull request to the upstream
 
 ## Markdown Style Guide
 

README.md

@@ -11,12 +11,15 @@ The latest documentation lives on https://alchemy.docs.buildwithfern.com/home
 ├── src/
 │   ├── openapi/     # REST API definitions (OpenAPI)
 │   └── openrpc/     # JSON-RPC API definitions (OpenRPC)
-├── fern/
-│   ├── <tab>/       # Written documentation for that tab (MDX)
-│   └── docs.yml     # Navigation and structure config
-└── build/           # Generated files - Do NOT make changes here
+└── fern/
+    ├── <tab>/       # Written documentation for that tab (MDX)
+    ├── api-specs/   # Dereferenced API Specs generated from definitions (gitignored)
+    └── docs.yml     # Navigation and structure config
 ```
 
+> \[!WARNING]
+> Account Kit documentation is maintained separately in the [aa-sdk repository](https://github.com/alchemyplatform/aa-sdk). See its [README](https://github.com/alchemyplatform/aa-sdk/blob/main/docs/README.md) for contribution guidelines.
+
 ## Getting Started
 
 ### Prerequisites
@@ -65,7 +68,7 @@ pnpm fern login
 pnpm fern generate --docs --preview
 ```
 
-This will take a minute as it needs to upload a lot files to generate the preview and it will output a preview URL.
+This will take a few minutes as it needs to upload a lot of files to generate the preview after which it will output a preview URL.
 
 ### Building API Specs
 
@@ -75,11 +78,11 @@ Production OpenAPI and OpenRPC specs are generated using scripts from their defi
 pnpm run generate
 ```
 
-This will generate all specs as dereferenced json files in the `build/` directory.
+This will generate all specs as dereferenced json files in the `fern/api-specs` directory.
 
 ### Validation
 
-You can validate both OpenAPI and OpenRPC using scripts.
+You can validate both OpenAPI and OpenRPC using these commands:
 
 ```bash
 # Validate REST API specs