chore: switch to nx monorepo [skip release] #432
Conversation
- Move SDK to packages/core/ maintaining @deepgram/sdk package name - Set up Nx workspace with build caching and parallel execution - Migrate from semantic-release to release-please manifest mode - Update all build configurations (TypeScript, Webpack, Jest) for monorepo - Update examples to reference new package structure - Add comprehensive test script for release process validation - Maintain backward compatibility with existing APIs and build outputs - Prepare structure for future package additions
- Update workspace database and file mappings - Clean up temporary server process files - Ensure workspace cache is properly tracked
- Add .nx/cache and .nx/workspace-data to .gitignore - Remove previously tracked Nx cache and workspace files - Follow Nx best practices for version control These directories contain build cache and workspace metadata that should not be committed to the repository.
WalkthroughRepository migrates to an Nx + pnpm monorepo with a new core package under packages/core. Test setup is converted to Nx projects. Release process switches from semantic-release to release-please with new CI workflows and a dry-run publish. Examples update import/script paths to the core package. Several tooling/config files are added, updated, or removed. Changes
Sequence Diagram(s)sequenceDiagram
participant Dev
participant GitHub
participant ReleasePlease as release-please
participant NPM as npm (dry-run)
Dev->>GitHub: Push to main / dispatch workflow
GitHub->>ReleasePlease: Run release-please-action (config + manifest)
ReleasePlease-->>GitHub: Outputs (releases_created, version, tag_name)
alt releases_created == true
GitHub->>NPM: npm publish --dry-run (tag: next|latest) in packages/core
else
GitHub-->>Dev: No release created
end
sequenceDiagram
participant Dev
participant CI as Release Test Workflow
participant Core as packages/core
participant ReleasePlease as release-please (dry)
Dev->>CI: Trigger on branch / dispatch
CI->>CI: Checkout, setup pnpm/Node
CI->>CI: pnpm install && pnpm run build
CI->>Core: Validate dist (CJS/ESM/UMD/types) + npm pack --dry-run
CI->>ReleasePlease: release-please-action (dry-run) and log outputs
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches
🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| name: Test Release Process | ||
| runs-on: ubuntu-latest | ||
|
|
||
| steps: | ||
| - uses: actions/checkout@v3 | ||
| with: | ||
| fetch-depth: 0 | ||
|
|
||
| - name: Install pnpm | ||
| uses: pnpm/action-setup@v2 | ||
| with: | ||
| version: latest | ||
|
|
||
| - name: Set up Node | ||
| uses: actions/setup-node@v3 | ||
| with: | ||
| node-version-file: ".nvmrc" | ||
| cache: "pnpm" | ||
|
|
||
| - name: Install dependencies and build | ||
| run: | | ||
| pnpm install --frozen-lockfile | ||
| pnpm run build | ||
| - name: Test Release Please (Dry Run) | ||
| uses: google-github-actions/release-please-action@v4 | ||
| id: release | ||
| with: | ||
| token: ${{ secrets.GITHUB_TOKEN }} | ||
| config-file: .release-please-config.json | ||
| manifest-file: .release-please-manifest.json | ||
|
|
||
| - name: Show Release Please Output | ||
| run: | | ||
| echo "🔍 Release Please Results:" | ||
| echo "Releases Created: ${{ steps.release.outputs.releases_created }}" | ||
| echo "Release Created: ${{ steps.release.outputs.release_created }}" | ||
| echo "Tag Name: ${{ steps.release.outputs.tag_name }}" | ||
| echo "Version: ${{ steps.release.outputs.version }}" | ||
| echo "PR Number: ${{ steps.release.outputs.pr }}" | ||
| - name: Test NPM Package Build | ||
| run: | | ||
| cd packages/core | ||
| echo "📦 Testing package contents:" | ||
| echo "Package name: $(cat package.json | jq -r .name)" | ||
| echo "Package version: $(cat package.json | jq -r .version)" | ||
| echo "Main entry: $(cat package.json | jq -r .main)" | ||
| echo "Module entry: $(cat package.json | jq -r .module)" | ||
| echo "Types entry: $(cat package.json | jq -r .types)" | ||
| echo "📁 Checking dist directory:" | ||
| ls -la dist/ || echo "No dist directory found" | ||
| echo "🧪 NPM Pack Test (creates tarball without publishing):" | ||
| npm pack --dry-run | ||
| - name: Validate Package Structure | ||
| run: | | ||
| cd packages/core | ||
| echo "🔍 Validating package structure:" | ||
| # Check required files exist | ||
| test -f dist/main/index.js && echo "✅ CommonJS build exists" || echo "❌ CommonJS build missing" | ||
| test -f dist/module/index.js && echo "✅ ESM build exists" || echo "❌ ESM build missing" | ||
| test -f dist/umd/deepgram.js && echo "✅ UMD build exists" || echo "❌ UMD build missing" | ||
| test -f dist/module/index.d.ts && echo "✅ Type definitions exist" || echo "❌ Type definitions missing" | ||
| echo "📊 Package size:" | ||
| du -sh dist/ |
Check warning
Code scanning / CodeQL
Workflow does not contain permissions Medium
Show autofix suggestion
Hide autofix suggestion
Copilot Autofix
AI 2 months ago
To fix the problem, you should add a permissions block to the workflow or to the specific job(s) that require it. The minimal starting point is contents: read, which allows the workflow to read repository contents but not write to them. If the workflow or job requires additional permissions (for example, to create or update pull requests), you should add only those specific permissions (e.g., pull-requests: write). In this case, since the workflow uses release-please-action, which may need to create or update pull requests, you should set contents: read and pull-requests: write at the job level for test-release. Edit the .github/workflows/release-test.yml file, adding the permissions block under the test-release job definition (line 11).
| @@ -9,6 +9,9 @@ | ||
| jobs: | ||
| test-release: | ||
| name: Test Release Process | ||
| permissions: | ||
| contents: read | ||
| pull-requests: write | ||
| runs-on: ubuntu-latest | ||
|
|
||
| steps: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🔭 Outside diff range comments (1)
examples/browser-prerecorded/index.html (1)
23-31: Fix shadowing of globaldeepgramin examplesUMD bundles expose a global named
deepgram. Declaringconst deepgram = deepgram.createClient(apiKey);in the same scope shadows that global (TDZ) and causes
“Cannot access 'deepgram' before initialization”. Rename the local client variable and update subsequent calls:• examples/browser-prerecorded/index.html (around line 23)
- const deepgram = deepgram.createClient(apiKey); + const dg = deepgram.createClient(apiKey); - const { result, error } = await deepgram.listen.prerecorded.transcribeUrl( + const { result, error } = await dg.listen.prerecorded.transcribeUrl(• examples/browser-live/index.html (around line 31)
- const deepgram = deepgram.createClient(apiKey); + const dg = deepgram.createClient(apiKey); - connection = deepgram.listen.live({ + connection = dg.listen.live({Optional: you can destructure once for clarity:
const { createClient } = deepgram; const dg = createClient(apiKey);
🧹 Nitpick comments (27)
.gitignore (1)
108-111: Nx cache ignores look good; consider confirming directory names for your Nx versionThe additions align with Nx’s current cache layout. Depending on your Nx version, you may also want to verify whether any of these additional paths should be ignored (names have changed across releases):
node:fs-style caches, daemon logs, or any other.nx/*transient files.Would you like me to cross-check your Nx version and recommend an exact ignore set?
.cursor/mcp.json (1)
1-12: Avoid using floating “latest” for MCP servers; pin versions and/or leverage pnpmUsing
npx -y nx-mcp@latestintroduces supply-chain and reproducibility risk. Prefer pinning a specific version and, since this repo standardizes on pnpm, considerpnpm dlx nx-mcp@<version>for consistency. Also ensure contributors havepipxinstalled fordeepctlor document an alternative.
- Proposal: add
nx-mcpas a devDependency and update the entry to use a pinned version (orpnpm dlx), and confirm team machines havepipxinstalled.
Do you want me to draft a docs snippet for contributor setup (pipx + pnpm) and a pinned config example?.eslintrc.js (1)
14-26: no-restricted-imports message conflicts with behavior; allow type-only imports and cover node: prefixed built-insThe rule’s message instructs to use type-only imports for Node built-ins, but the config currently blocks all imports (including type-only). Also,
node:-prefixed specifiers aren’t covered. Suggest enablingallowTypeImportsand includingnode:*variants.Apply this diff:
"no-restricted-imports": [ "error", { patterns: [ { - group: ["stream", "fs", "path", "crypto", "os", "child_process", "url", "util"], - message: - 'Node.js built-in modules should use type-only imports. Use: import type { ... } from "..."', + group: [ + "stream", + "fs", + "path", + "crypto", + "os", + "child_process", + "url", + "util", + "node:stream", + "node:fs", + "node:path", + "node:crypto", + "node:os", + "node:child_process", + "node:url", + "node:util" + ], + message: 'Node.js built-in modules should use type-only imports. Use: import type { ... } from "..."', + allowTypeImports: true }, ], }, ],Optionally, scope this restriction to app/library source (not tests) using ESLint overrides if tests legitimately import Node built-ins at runtime.
Want me to draft an overrides block that limits this rule to packages/*/src?
commitlint.config.js (1)
1-3: LGTM; consider centralizing config-file exceptions via ESLint overridesPer-file disables work, but you can centralize them in
.eslintrc.jsusing an overrides block targeting config files to reduce repetition across the repo.Example override to add in
.eslintrc.js:overrides: [ { files: [ '*.config.{js,cjs,mjs}', 'commitlint.config.js', '.eslintrc.js', 'jest.config.{js,cjs,mjs}', 'prettier.config.{js,cjs,mjs}', 'vite.config.{js,cjs,mjs}', 'webpack.config.{js,cjs,mjs}', ], rules: { '@typescript-eslint/no-var-requires': 'off', '@typescript-eslint/no-require-imports': 'off', }, }, ]packages/core/tests/unit/live-client-message-handling.test.ts (1)
565-568: Formatting-only change to provider endpoint literal — OKMultiline object + trailing comma are stylistic; no behavior impact. Ensure Prettier/ESLint rules align with trailing commas in multiline literals.
.cursor/rules/nx-rules.mdc (1)
1-5: Populate front matter for clarity/scopingMinor: consider setting
descriptionand narrowingglobsso rules only apply where intended, which can reduce noise in mixed repos.Apply something like:
--- -description: -globs: +description: "Guidance for using Nx Console tools in this workspace" +globs: + - "**/*" alwaysApply: true ---.github/workflows/release.yml (1)
41-65: Tighten dry-run publish step and improve prerelease detection
- Clean up credentials after use to reduce risk.
- Make the prerelease check more robust (handle numeric identifiers, e.g., -beta.1).
- Fail fast on script errors.
Apply:
- run: | - cd packages/core + run: | + set -euo pipefail + cd packages/core echo "🧪 DRY RUN: Would publish to NPM" @@ - echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc + echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc @@ - # Check if version contains prerelease identifiers - if [[ "$PACKAGE_VERSION" =~ -[a-zA-Z] ]]; then + # Check if version contains prerelease identifiers (e.g., -alpha, -beta.1, -rc.0) + if [[ "$PACKAGE_VERSION" =~ -[0-9A-Za-z] ]]; then echo "📦 Publishing prerelease version with --tag next" npm publish --dry-run --access public --tag next else echo "📦 Publishing stable version with --tag latest" npm publish --dry-run --access public --tag latest fi + # Cleanup credentials + rm -f ~/.npmrcOptional: update action versions to latest majors for security/performance:
- actions/checkout@v4
- actions/setup-node@v4
- pnpm/action-setup@v4
.github/workflows/release-test.yml (2)
1-8: Set explicit minimal permissions for GITHUB_TOKENThis workflow doesn’t need write access; set least-privilege to satisfy CodeQL and harden the workflow.
name: Release Test on: push: branches: - test-monorepo-release workflow_dispatch: +permissions: + contents: read
15-29: Optional: Update action versions to latest majorsKeeping runner actions on current majors helps with performance and security hardening.
- actions/checkout@v4
- actions/setup-node@v4
- pnpm/action-setup@v4
If you agree, I can open a quick PR to bump these.
packages/core/jest.config.js (2)
28-29: Align coverage output with Nx target outputs.Nx test target typically declares outputs at {workspaceRoot}/coverage/packages/core. Your Jest config writes to "coverage" under the package, which can desync Nx caching/artifacts.
Consider updating the coverageDirectory to match Nx’s output path:
- coverageDirectory: "coverage", + coverageDirectory: "<rootDir>/../../coverage/packages/core",Alternatively, update the Nx project test.outputs to point to packages/core/coverage to keep them in sync. Consistency is the key either way.
10-14: Add subpath mapper to support deep imports in tests (optional).If any tests import subpaths (e.g., @deepgram/sdk/foo), add a subpath mapper to avoid resolution issues.
moduleNameMapper: { "^@/(.*)$": "<rootDir>/src/$1", "^@deepgram/sdk$": "<rootDir>/src/index.ts", + "^@deepgram/sdk/(.*)$": "<rootDir>/src/$1", },examples/node-speak/index.js (1)
4-4: Prefer importing the package by name to leverage workspace linking.Using the workspace package name keeps examples resilient to directory changes and matches how users consume the SDK. It also avoids requiring a local build path.
-const { createClient } = require("../../packages/core/dist/main/index"); +const { createClient } = require("@deepgram/sdk");Optional hardening outside this line:
- Add an env guard to fail fast if the API key is missing:
if (!process.env.DEEPGRAM_API_KEY) { console.error("Missing DEEPGRAM_API_KEY in environment."); process.exit(1); }
- Consider wrapping the top-level invocation in try/catch to exit with a non-zero code on failure for CI safety.
examples/node-prerecorded/index.js (1)
4-4: Use the package name instead of a relative dist path for examples.This keeps examples cleaner and aligned with consumer usage patterns in a monorepo.
-const { createClient } = require("../../packages/core/dist/main/index"); +const { createClient } = require("@deepgram/sdk");Optional improvements outside this line:
- Guard against missing API key:
if (!process.env.DEEPGRAM_API_KEY) { console.error("Missing DEEPGRAM_API_KEY in environment."); process.exit(1); }
- Avoid logging full Buffer contents (it’s noisy and large). Log metadata instead:
// Replace: // console.log("Transcribing file", file); // With: console.log("Transcribing file", { bytes: file.length });examples/node-read/index.js (1)
4-4: Reference the SDK via its workspace package name.Consistent with the monorepo and user-facing usage, import from @deepgram/sdk rather than a relative dist path.
-const { createClient } = require("../../packages/core/dist/main/index"); +const { createClient } = require("@deepgram/sdk");Optional: add a quick env guard for DEEPGRAM_API_KEY to provide a clearer error when missing.
packages/core/tsconfig.module.json (1)
3-7: Consider setting moduleResolution to Bundler for modern ESM library builds.For libraries targeting ESM output ("module": "ES2020"), TypeScript’s "moduleResolution": "Bundler" reduces friction with package exports and avoids Node ESM pitfalls.
"compilerOptions": { "outDir": "dist/module", "target": "ES2020", - "module": "ES2020" + "module": "ES2020", + "moduleResolution": "Bundler" }examples/node-live-token/index.js (1)
4-4: Path update aligns with monorepo move; consider importing by package name for resilienceUsing a relative dist path is fine for local repo examples, but it’s brittle to layout changes. If the package is linked in the workspace, importing by name is more stable and mirrors how consumers will use it.
- Verify Nx build/output is configured to emit to packages/core/dist/main/index so this example works after nx build core.
- Optional diff to prefer the published package name:
-const { createClient, LiveTranscriptionEvents } = require("../../packages/core/dist/main/index"); +const { createClient, LiveTranscriptionEvents } = require("@deepgram/sdk");pnpm-workspace.yaml (1)
1-2: Workspace scope is correct; consider using a recursive glob for future nested packagesIf you later nest packages (e.g., packages/clients/web), a recursive pattern avoids future edits.
-packages: - - "packages/*" +packages: + - "packages/**"examples/node-speak-live/index.js (1)
4-4: Path update matches monorepo structure; consider importing by package nameSame note as other Node examples: importing by package name mirrors consumer usage and is less sensitive to internal directory layouts.
- Verify that LiveTTSEvents remains a named export from the new entry point.
Optional diff:
-const { createClient, LiveTTSEvents } = require("../../packages/core/dist/main/index"); +const { createClient, LiveTTSEvents } = require("@deepgram/sdk");examples/node-live/index.js (1)
4-4: Prefer importing the workspace package instead of a deep relative dist pathUsing a deep relative path to built artifacts is brittle and ties examples to internal build layout. Since the package name and API are preserved, import from the package to improve resilience and developer UX.
Apply this diff:
-const { createClient, LiveTranscriptionEvents } = require("../../packages/core/dist/main/index"); +const { createClient, LiveTranscriptionEvents } = require("@deepgram/sdk");If you need to run examples against local sources without publishing, consider ensuring pnpm links workspace packages (pnpm -w i) and adding an Nx target that builds core before running examples. I can help wire that up if desired.
packages/core/tsconfig.json (1)
3-3: Redundant exclude patternExcluding node_modules is implicit. The explicit "exclude": ["node_modules/**/*.ts"] is unnecessary and can be dropped to reduce noise.
Apply this diff:
- "exclude": ["node_modules/**/*.ts"],nx.json (1)
3-15: Include shared global config files in namedInputs.sharedGlobals to improve cache correctnessCurrently sharedGlobals is empty. Changes to root config files (e.g., package manager lockfile, tsconfig base, Nx config) won’t invalidate caches unless explicitly referenced elsewhere. Populate sharedGlobals with common root configs to ensure accurate cache invalidation.
Apply this diff:
"namedInputs": { "default": ["{projectRoot}/**/*", "sharedGlobals"], "production": [ "default", "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)", "!{projectRoot}/tsconfig.spec.json", "!{projectRoot}/jest.config.[jt]s", "!{projectRoot}/.eslintrc.json", "!{projectRoot}/src/test-setup.[jt]s", "!{projectRoot}/test-setup.[jt]s" ], - "sharedGlobals": [] + "sharedGlobals": [ + "{workspaceRoot}/package.json", + "{workspaceRoot}/pnpm-lock.yaml", + "{workspaceRoot}/nx.json", + "{workspaceRoot}/tsconfig.base.json", + "{workspaceRoot}/jest.preset.js", + "{workspaceRoot}/.eslintrc.json", + "{workspaceRoot}/.eslintignore" + ] },This is non-breaking and helps Nx’s computation cache stay accurate when root configs change.
package.json (2)
30-31: Optional: run many with parallelism and cache-awarenessYou can speed up CI and leverage Nx better by running in parallel and skipping up-to-date tasks.
For example:
- nx run-many -t build --parallel --skip-nx-cache=false
- nx run-many -t test --parallel
No change required if you already rely on Nx’s default concurrency.
Also applies to: 36-37, 40-41
73-73: Typescript 4.5 is quite old for Nx 21Nx 21 works well with TS 5.x. Consider planning an upgrade to avoid interop issues with newer tooling and to get better type-checking performance.
docs/Nx Monorepo Setup.md (2)
163-166: Prefer package imports in examples over dist pathsPoint examples to import @deepgram/sdk (workspace protocol) instead of dist paths. This keeps examples stable if the build layout changes and tests actual consumer ergonomics.
Example:
- pnpm --filter "./examples/**" add @deepgram/sdk@workspace:*
- In examples: import { Deepgram } from "@deepgram/sdk";
41-48: Nit: compress “Entry Points” listCurrent bullets are correct but slightly verbose. Consider a concise mapping to reduce noise.
For example:
- main: dist/main/index.js
- module: dist/module/index.js
- types: dist/module/index.d.ts
- umd: dist/umd/deepgram.js
test-release.sh (2)
39-43: Avoid cat | jq pattern (efficiency/readability)Use jq file arguments directly.
Apply this diff:
-echo " Name: $(cat package.json | jq -r .name)" -echo " Version: $(cat package.json | jq -r .version)" -echo " Main: $(cat package.json | jq -r .main)" -echo " Module: $(cat package.json | jq -r .module)" -echo " Types: $(cat package.json | jq -r .types)" +echo " Name: $(jq -r .name package.json)" +echo " Version: $(jq -r .version package.json)" +echo " Main: $(jq -r .main package.json)" +echo " Module: $(jq -r .module package.json)" +echo " Types: $(jq -r .types package.json)"
82-86: Keep release-please stderr visible during dry-runRedirecting stderr to /dev/null can hide useful diagnostics. Prefer showing output and handling non-zero exit codes explicitly.
Apply this diff:
- release-please release-pr \ + release-please release-pr \ --config-file=.release-please-config.json \ --manifest-file=.release-please-manifest.json \ --dry-run \ - --trace 2>/dev/null || echo " ℹ️ Release Please dry-run completed (check output above)" + --trace || echo " ℹ️ Release Please dry-run completed (see output above)"
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
⛔ Files ignored due to path filters (39)
packages/core/tests/__fixtures__/spacewalk.wavis excluded by!**/*.wavpackages/core/tests/e2e/__snapshots__/auth-grant-token.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/listen-transcribe-file-callback.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/listen-transcribe-file.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/listen-transcribe-url-callback.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/listen-transcribe-url.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-create-project-key.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-all-models.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-model.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project-balance.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project-balances.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project-invites.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project-key.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project-keys.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project-member-scopes.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project-members.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project-usage-fields.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project-usage-request.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project-usage-requests.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project-usage-summary.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-project.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-projects.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-get-token-details.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-leave-project.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-send-project-invite.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-update-project-member-scope.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/manage-update-project.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/models-get-all.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/models-get-model.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/read-analyze-text-callback.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/read-analyze-text.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/read-analyze-url-callback.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/read-analyze-url.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/selfhosted-create-credentials.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/selfhosted-delete-credentials.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/selfhosted-get-credentials.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/selfhosted-list-credentials.test.ts.snapis excluded by!**/*.snappackages/core/tests/e2e/__snapshots__/speak-request.test.ts.snapis excluded by!**/*.snappnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (38)
.cursor/mcp.json(1 hunks).cursor/rules/nx-rules.mdc(1 hunks).eslintrc-examples.js(0 hunks).eslintrc.js(1 hunks).github/workflows/release-test.yml(1 hunks).github/workflows/release.yml(1 hunks).gitignore(1 hunks).release-please-config.json(1 hunks).release-please-manifest.json(1 hunks).releaserc.json(0 hunks).vscode/settings.json(1 hunks)commitlint.config.js(1 hunks)docs/Nx Monorepo Setup.md(1 hunks)examples/browser-live/index.html(1 hunks)examples/browser-prerecorded/index.html(1 hunks)examples/node-agent-live/index.js(3 hunks)examples/node-live-token/index.js(1 hunks)examples/node-live/index.js(1 hunks)examples/node-prerecorded/index.js(1 hunks)examples/node-read/index.js(1 hunks)examples/node-speak-live/index.js(1 hunks)examples/node-speak/index.js(1 hunks)jest.config.js(1 hunks)jest.preset.js(1 hunks)nx.json(1 hunks)package.json(4 hunks)packages/core/jest.config.js(1 hunks)packages/core/package.json(1 hunks)packages/core/project.json(1 hunks)packages/core/src/packages/AbstractLiveClient.ts(3 hunks)packages/core/tests/unit/live-client-message-handling.test.ts(1 hunks)packages/core/tsconfig.json(1 hunks)packages/core/tsconfig.module.json(1 hunks)pnpm-workspace.yaml(1 hunks)scripts/test-offline.js(0 hunks)test-release.sh(1 hunks)tsconfig.json(1 hunks)tsconfig.module.json(0 hunks)
💤 Files with no reviewable changes (4)
- tsconfig.module.json
- scripts/test-offline.js
- .releaserc.json
- .eslintrc-examples.js
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2024-10-08T01:22:26.486Z
Learnt from: naomi-lgbt
PR: deepgram/deepgram-js-sdk#333
File: .markdownlint.jsonc:3-5
Timestamp: 2024-10-08T01:22:26.486Z
Learning: In the deepgram-js-sdk project, disabling the MarkdownLint rules `"line-length"`, `"no-bare-urls"`, and `"no-duplicate-heading"` is acceptable for GitHub documentation files.
Applied to files:
.vscode/settings.json
📚 Learning: 2024-10-08T01:26:16.711Z
Learnt from: naomi-lgbt
PR: deepgram/deepgram-js-sdk#333
File: .github/workflows/CI.yml:50-51
Timestamp: 2024-10-08T01:26:16.711Z
Learning: In the `deepgram-js-sdk` project, linting configuration files may have custom names that differ from the default ones.
Applied to files:
package.json
🧬 Code Graph Analysis (5)
examples/node-live/index.js (6)
examples/node-agent-live/index.js (1)
require(4-4)examples/node-live-token/index.js (1)
require(4-4)examples/node-read/index.js (1)
require(4-4)examples/node-speak-live/index.js (3)
require(4-4)require(5-5)require(6-6)examples/node-prerecorded/index.js (3)
require(4-4)require(5-5)require(6-6)examples/node-speak/index.js (3)
require(4-4)require(5-5)require(6-6)
examples/node-prerecorded/index.js (6)
examples/node-agent-live/index.js (1)
require(4-4)examples/node-live-token/index.js (1)
require(4-4)examples/node-live/index.js (1)
require(4-4)examples/node-read/index.js (1)
require(4-4)examples/node-speak-live/index.js (3)
require(4-4)require(5-5)require(6-6)examples/node-speak/index.js (3)
require(4-4)require(5-5)require(6-6)
examples/node-read/index.js (6)
examples/node-agent-live/index.js (1)
require(4-4)examples/node-live-token/index.js (1)
require(4-4)examples/node-live/index.js (1)
require(4-4)examples/node-speak-live/index.js (3)
require(4-4)require(5-5)require(6-6)examples/node-prerecorded/index.js (3)
require(4-4)require(5-5)require(6-6)examples/node-speak/index.js (3)
require(4-4)require(5-5)require(6-6)
examples/node-live-token/index.js (6)
examples/node-agent-live/index.js (1)
require(4-4)examples/node-live/index.js (1)
require(4-4)examples/node-read/index.js (1)
require(4-4)examples/node-speak-live/index.js (3)
require(4-4)require(5-5)require(6-6)examples/node-prerecorded/index.js (3)
require(4-4)require(5-5)require(6-6)examples/node-speak/index.js (3)
require(4-4)require(5-5)require(6-6)
examples/node-agent-live/index.js (6)
examples/node-live-token/index.js (1)
require(4-4)examples/node-live/index.js (1)
require(4-4)examples/node-read/index.js (1)
require(4-4)examples/node-speak-live/index.js (3)
require(4-4)require(5-5)require(6-6)examples/node-prerecorded/index.js (3)
require(4-4)require(5-5)require(6-6)examples/node-speak/index.js (3)
require(4-4)require(5-5)require(6-6)
🪛 GitHub Check: CodeQL
.github/workflows/release-test.yml
[warning] 11-80: Workflow does not contain permissions
Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {{contents: read}}
🪛 Shellcheck (0.10.0)
test-release.sh
[warning] 28-28: Use 'cd ... || exit' or 'cd ... || return' in case cd fails.
(SC2164)
🪛 LanguageTool
docs/Nx Monorepo Setup.md
[grammar] ~41-~41: There might be a mistake here.
Context: ...SDK functionality: - Package Name: @deepgram/sdk - Build Outputs: CommonJS (dist/main/)...
(QB_NEW_EN)
[grammar] ~42-~42: There might be a mistake here.
Context: ... ESM (dist/module/), UMD (dist/umd/) - Entry Points: - Main: `dist/main/ind...
(QB_NEW_EN)
[grammar] ~43-~43: There might be a mistake here.
Context: ...), UMD (dist/umd/) - Entry Points: - Main: dist/main/index.js - Module: `...
(QB_NEW_EN)
[grammar] ~44-~44: There might be a mistake here.
Context: ...st/umd/) - **Entry Points**: - Main: dist/main/index.js - Module:dist/module/index.js` - Types...
(QB_NEW_EN)
[grammar] ~45-~45: There might be a mistake here.
Context: ... Main: dist/main/index.js - Module: dist/module/index.js - Types: dist/module/index.d.ts - UMD:...
(QB_NEW_EN)
[grammar] ~46-~46: There might be a mistake here.
Context: ...dule: dist/module/index.js - Types: dist/module/index.d.ts - UMD: dist/umd/deepgram.js ## Build Sy...
(QB_NEW_EN)
[grammar] ~55-~55: There might be a mistake here.
Context: ...: Intelligent caching of build artifacts - Parallel Execution: Multiple tasks run...
(QB_NEW_EN)
[grammar] ~56-~56: There might be a mistake here.
Context: ...ion**: Multiple tasks run simultaneously - Dependency Management: Automatic detec...
(QB_NEW_EN)
[grammar] ~57-~57: There might be a mistake here.
Context: ...omatic detection of package dependencies - Target Defaults: Consistent build beha...
(QB_NEW_EN)
[grammar] ~64-~64: There might be a mistake here.
Context: ...cess (TypeScript compilation + bundling) - test: Run Jest test suite - lint: ESLint c...
(QB_NEW_EN)
[grammar] ~65-~65: There might be a mistake here.
Context: ... bundling) - test: Run Jest test suite - lint: ESLint code quality checks - clean: ...
(QB_NEW_EN)
[grammar] ~66-~66: There might be a mistake here.
Context: ...ite - lint: ESLint code quality checks - clean: Remove build artifacts ## Development...
(QB_NEW_EN)
[grammar] ~130-~130: There might be a mistake here.
Context: ...tomated releases: - Configuration: .release-please-config.json - Manifest: `.release-please-manifest.js...
(QB_NEW_EN)
[grammar] ~131-~131: There might be a mistake here.
Context: ...ase-please-config.json- **Manifest**:.release-please-manifest.json- **Tag Format**:@deepgram/sdk@{version}` ...
(QB_NEW_EN)
[grammar] ~132-~132: There might be a mistake here.
Context: ...please-manifest.json- **Tag Format**:@deepgram/sdk@{version}` - Release Strategy: Node.js semantic ver...
(QB_NEW_EN)
[grammar] ~163-~163: There might be a mistake here.
Context: ...e: - Node.js Examples: Import from ../../packages/core/dist/main/index - Browser Examples: Reference `../../pac...
(QB_NEW_EN)
[grammar] ~164-~164: There might be a mistake here.
Context: ...ndex- **Browser Examples**: Reference../../packages/core/dist/umd/deepgram.js` - Functionality: All examples maintain o...
(QB_NEW_EN)
[grammar] ~171-~171: There might be a mistake here.
Context: ...orkspace configuration and build caching - jest.config.js: Root Jest configuration using Nx prese...
(QB_NEW_EN)
[grammar] ~172-~172: There might be a mistake here.
Context: ... Root Jest configuration using Nx preset - tsconfig.json: Root TypeScript configuration with pro...
(QB_NEW_EN)
[grammar] ~173-~173: There might be a mistake here.
Context: ...pt configuration with project references - pnpm-workspace.yaml: PNPM workspace definition ### Package...
(QB_NEW_EN)
[grammar] ~180-~180: There might be a mistake here.
Context: ...json: Package metadata and dependencies - project.json: Nx project configuration - tsconfig.j...
(QB_NEW_EN)
[grammar] ~181-~181: There might be a mistake here.
Context: ...project.json: Nx project configuration - tsconfig.json: TypeScript compilation settings - `jes...
(QB_NEW_EN)
[grammar] ~182-~182: There might be a mistake here.
Context: ...g.json: TypeScript compilation settings - jest.config.js: Jest test configuration - webpack.con...
(QB_NEW_EN)
[grammar] ~183-~183: There might be a mistake here.
Context: ...jest.config.js: Jest test configuration - webpack.config.js`: UMD bundle configuration (if applicabl...
(QB_NEW_EN)
[grammar] ~201-~201: There might be a mistake here.
Context: ... packages/shared/ or similar - Define as dependency in consuming packages - Use ...
(QB_NEW_EN)
[grammar] ~210-~210: There might be a mistake here.
Context: ...outputs based on: - Source code changes - Dependency changes - Configuration chang...
(QB_NEW_EN)
[grammar] ~211-~211: There might be a mistake here.
Context: ...Source code changes - Dependency changes - Configuration changes - Environment vari...
(QB_NEW_EN)
[grammar] ~212-~212: There might be a mistake here.
Context: ...pendency changes - Configuration changes - Environment variables ### Parallel Exec...
(QB_NEW_EN)
[grammar] ~219-~219: There might be a mistake here.
Context: ...omatic detection of parallelizable tasks - Respects inter-package dependencies - Co...
(QB_NEW_EN)
[grammar] ~220-~220: There might be a mistake here.
Context: ...ks - Respects inter-package dependencies - Configurable concurrency limits ### Inc...
(QB_NEW_EN)
[grammar] ~227-~227: There might be a mistake here.
Context: ...e rebuilt: - Git-based change detection - Dependency graph analysis - Smart rebuil...
(QB_NEW_EN)
[grammar] ~228-~228: There might be a mistake here.
Context: ...ge detection - Dependency graph analysis - Smart rebuild strategies ## Troubleshoo...
(QB_NEW_EN)
[grammar] ~235-~235: There might be a mistake here.
Context: .... Cache Issues: Clear Nx cache with nx reset 2. Dependency Conflicts: Run `pnpm instal...
(QB_NEW_EN)
[grammar] ~236-~236: There might be a mistake here.
Context: ...reset2. **Dependency Conflicts**: Runpnpm install --force` 3. Build Failures: Check individual packa...
(QB_NEW_EN)
[grammar] ~237-~237: There might be a mistake here.
Context: ... Check individual package configurations 4. Test Issues: Verify Jest configuration...
(QB_NEW_EN)
🔇 Additional comments (30)
.vscode/settings.json (1)
4-5: Nx Console setting key is correct
Verified thatnxConsole.generateAiAgentRulesis the official VS Code setting for the Nx Console extension (source). No changes needed..eslintrc.js (1)
1-3: LGTM on file-scope rule disables for a Node CJS configThese directives are appropriate for a CommonJS config file.
packages/core/src/packages/AbstractLiveClient.ts (3)
17-21: Type-only whitespace normalization — OKConstructor signature spacing after
newis cosmetic; no impact on types or runtime behavior.
199-199: No-oponcloseassignment — unchanged behaviorWhitespace-only tweak; behavior remains: suppress
onclosecallbacks during explicit disconnect. Assuming this is intentional to avoid duplicate Close emissions, this is fine.
528-534: Arrow function spacing — OKPure formatting on dummy WS handlers; no functional changes.
packages/core/jest.config.js (2)
16-18: setup.ts verified; no stub required.
The script confirms thatpackages/core/tests/setup.tsexists, so the Jest config is valid as-is.
34-42: tsconfig.json is CommonJS—no Jest config changes requiredVerified that
packages/core/tsconfig.jsonhascompilerOptions.moduleset to"CommonJS", so the existing ts-jest transform inpackages/core/jest.config.js(lines 34–42) is correct. No updates needed..release-please-manifest.json (1)
1-3: Manifest Version Matches Package VersionBoth
.release-please-manifest.jsonandpackages/core/package.jsonare at version 4.11.2, and.release-please-config.jsoncorrectly references thepackages/corepath. No further action needed.examples/browser-live/index.html (1)
13-13: UMD path updated; verify the browser global remains window.deepgramThe UMD build should still expose window.deepgram. Since only the path changed, confirm the global name didn’t change with the new bundling/output.
- Open the page and check in DevTools: typeof window.deepgram should be "object".
- If you plan to run this example outside the repo, consider loading from the published package CDN instead of a local dist path.
examples/browser-prerecorded/index.html (1)
12-12: LGTM: Example now points to the core UMD bundleThe script path aligns with the new monorepo structure and the core package’s UMD output.
jest.preset.js (1)
4-8: LGTM: Nx Jest preset configuration is correctUsing getJestProjects() enables multi-project test discovery under Nx. This matches the monorepo migration.
tsconfig.json (1)
1-16: LGTM! Proper composite TypeScript configuration for monorepo setup.The configuration correctly transitions from a source-inclusion setup to a project-references-based composite build. The empty
filesandincludearrays combined with the reference to./packages/coreindicate that build input now comes from the referenced project, which aligns with the Nx monorepo architecture.packages/core/package.json (3)
1-8: LGTM! Package metadata properly configured.The package name, version, and metadata are correctly preserved from the migration, maintaining backward compatibility as stated in the PR objectives.
35-37: LGTM! Entry points properly configured for multiple module formats.The main, module, and types entry points are correctly set to support CommonJS, ES modules, and TypeScript declarations respectively. This maintains the expected module resolution behavior.
63-64: LGTM! CDN entry points correctly configured.Both jsdelivr and unpkg point to the UMD bundle, which is appropriate for CDN distribution and browser usage.
examples/node-agent-live/index.js (3)
4-4: LGTM! Import path updated for monorepo structure.The import path correctly references the new core package location under
packages/core/dist/main/index, which aligns with the monorepo migration and is consistent with other example files.
26-26: LGTM! Quote style change is consistent.The change from single quotes to double quotes for the string comparison maintains functionality while improving consistency with the surrounding code style.
44-45: LGTM! Trailing commas added for better maintainability.The addition of trailing commas in the agent configuration object improves code maintainability by making future additions cleaner in version control diffs.
Also applies to: 50-51, 53-53
packages/core/project.json (3)
1-5: LGTM! Nx project metadata properly configured.The project configuration correctly identifies this as a library project with appropriate source root and schema reference.
29-35: LGTM! Jest test configuration properly integrated with Nx.The test target correctly uses the Nx Jest executor with appropriate output directory and Jest configuration file path.
36-42: LGTM! ESLint configuration properly set up.The lint target correctly runs ESLint with zero warnings tolerance, which enforces code quality standards.
.release-please-config.json (5)
3-8: LGTM! Package mapping correctly configured.The package configuration properly maps
packages/coreto the@deepgram/sdkpackage name and component, maintaining the existing package identity.
10-11: LGTM! Conservative version bumping strategy.Disabling minor pre-major and patch-for-minor pre-major bumps provides more predictable versioning behavior, which is appropriate for an SDK.
12-15: LGTM! Draft releases with version tags configured properly.The configuration enables draft releases with version tags using "@" as separator, which allows for review before publication.
20-21: LGTM! GitHub automation disabled as intended.Skipping GitHub release and pull request creation aligns with the PR objective to use temporary skip flags during migration. Remember to re-enable these after the migration is complete.
2-2: bootstrap-sha set to HEAD is correct for initial setupSince there are no prior
chore: releasecommits in this repo, using"bootstrap-sha": "HEAD"is appropriate for the initial Release Please run. No change is needed at this time. Once the first release is created, you can update this to the generated release commit SHA or tag to anchor subsequent runs.package.json (2)
32-32: Custom ESLint config for examples looks intentionalThe nonstandard .eslintrc-examples.js aligns with prior repo practices for examples.
45-47: Nx lint executor verified – no missing @nx/eslint plugin
All lint targets use thenx:run-commandsexecutor, so you don’t need to install@nx/eslint. No changes required.docs/Nx Monorepo Setup.md (1)
28-33: Minor polish: ensure file list reflects repo realityDouble-check that jest.preset.js exists at root if documented here. If root uses only jest.config.js with getJestProjects, update wording accordingly.
jest.config.js (1)
4-8: LGTM: root Jest delegates to Nx projectsUsing getJestProjects() is the recommended Nx approach; per-package configs can own detailed settings.
| - name: Create Release Pull Request or Publish to NPM | ||
| uses: google-github-actions/release-please-action@v4 | ||
| id: release | ||
| with: | ||
| token: ${{ secrets.GITHUB_TOKEN }} | ||
| config-file: .release-please-config.json | ||
| manifest-file: .release-please-manifest.json | ||
|
|
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Harden GITHUB_TOKEN permissions (CodeQL hint) and declare only what’s needed
Explicit permissions improve security and satisfy the CodeQL warning. Release Please needs write perms for contents and PRs. Add at the job (or workflow) level:
# top-level (recommended) or under jobs.release:
permissions:
contents: write # needed to create tags/releases
pull-requests: write # needed to open/update release PRsOptionally add a concurrency group to prevent overlapping releases:
concurrency:
group: release-${{ github.ref }}
cancel-in-progress: false[suggest_optional_refactor]
🏁 Script executed:
#!/bin/bash
# Check if permissions/concurrency already exist in workflow
echo "== release.yml permissions block =="
rg -n -C2 '^\s*permissions:\s*$' .github/workflows/release.yml || echo "No explicit permissions block found"
echo "== concurrency block =="
rg -n -C2 '^\s*concurrency:\s*$' .github/workflows/release.yml || echo "No concurrency block found"
# Verify Release Please config has skip mechanisms to honor '[skip release]' intent
echo "== release-please config =="
cat .release-please-config.json 2>/dev/null || echo "Missing .release-please-config.json"
echo "== checking for skip-labels =="
rg -n '"skip-labels"\s*:' .release-please-config.json || echo "No skip-labels configured"Length of output: 1311
Harden workflow permissions, add concurrency, and fix Release Please skip logic
To satisfy the CodeQL warning and ensure releases only run when intended:
-
Add an explicit
permissionsblock (at the top level or underjobs.release) in.github/workflows/release.yml:permissions: contents: write # needed to create tags/releases pull-requests: write # needed to open/update release PRs
-
(Optional) Prevent overlapping runs by adding a
concurrencygroup:concurrency: group: release-${{ github.ref }} cancel-in-progress: false
-
Update your release-please config (
.release-please-config.json) so that releases are skipped only when explicitly requested, rather than always disabled:- Remove these two flags (they currently disable all releases):
"skip-github-release": true, "skip-github-pull-request": true,
- Add a conditional skip based on a label, for example:
"skip-labels": ["skip release"]
- Remove these two flags (they currently disable all releases):
This grants least privilege to your workflow, prevents unintended parallel runs, and restores the intended “[skip release]” behavior.
🤖 Prompt for AI Agents
In .github/workflows/release.yml around lines 33 to 40, the workflow is missing
explicit permissions, concurrency control, and the release-please skip logic is
too broad; add a permissions block granting contents: write and pull-requests:
write (either top-level or under jobs.release), add a concurrency group (e.g.,
group based on github.ref with cancel-in-progress set as desired) to prevent
overlapping runs, and update .release-please-config.json by removing the global
"skip-github-release" and "skip-github-pull-request" flags and instead add a
conditional skip like "skip-labels": ["skip release"] so releases are only
skipped when explicitly requested.
| "lint": "run-s lint:*", | ||
| "lint:js": "eslint -c .eslintrc-examples.js examples --max-warnings 0", | ||
| "lint:md": "markdownlint **/*.md *.md", | ||
| "lint:yml": "yamllint .github/workflows", |
There was a problem hiding this comment.
Fix YAML linter script: uses wrong CLI binary
Script calls yamllint but devDependency is yaml-lint. This will fail locally/CI.
Apply this diff to align the script with the installed tool:
- "lint:yml": "yamllint .github/workflows",
+ "lint:yml": "yaml-lint -q \"./.github/workflows/**/*.yml\"",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "lint:yml": "yamllint .github/workflows", | |
| "lint:yml": "yaml-lint -q \"./.github/workflows/**/*.yml\"", |
🤖 Prompt for AI Agents
package.json around line 35: the "lint:yml" script invokes the wrong CLI
("yamllint") while the repo's devDependency is "yaml-lint"; update the script to
call the installed binary ("yaml-lint .github/workflows") so CI and local runs
use the correct tool, or alternatively install the yamllint package and update
devDependencies to match—prefer changing the script to "yaml-lint
.github/workflows" to align with the declared devDependency.
| "docs": "typedoc --entryPoints packages/core/src/index.ts --out docs/ --includes packages/core/src/packages/**/*.ts --emit none", | ||
| "docs:json": "typedoc --entryPoints packages/core/src/index.ts --includes packages/core/src/packages/**/*.ts --json docs/spec.json --emit none", |
There was a problem hiding this comment.
Typedoc flags likely invalid; docs scripts won’t emit output
TypeDoc 0.22 does not support an --emit none flag, and includes expects a directory, not a ts glob. As written, docs generation will likely error or produce nothing.
Apply this diff to generate docs and JSON as intended:
- "docs": "typedoc --entryPoints packages/core/src/index.ts --out docs/ --includes packages/core/src/packages/**/*.ts --emit none",
- "docs:json": "typedoc --entryPoints packages/core/src/index.ts --includes packages/core/src/packages/**/*.ts --json docs/spec.json --emit none",
+ "docs": "typedoc --entryPoints packages/core/src/index.ts --out docs/",
+ "docs:json": "typedoc --entryPoints packages/core/src/index.ts --json docs/spec.json",If you do want to include extra markdown content, point --includes to a docs/includes directory (not a glob of .ts files) and add those files there.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "docs": "typedoc --entryPoints packages/core/src/index.ts --out docs/ --includes packages/core/src/packages/**/*.ts --emit none", | |
| "docs:json": "typedoc --entryPoints packages/core/src/index.ts --includes packages/core/src/packages/**/*.ts --json docs/spec.json --emit none", | |
| "docs": "typedoc --entryPoints packages/core/src/index.ts --out docs/", | |
| "docs:json": "typedoc --entryPoints packages/core/src/index.ts --json docs/spec.json", |
🤖 Prompt for AI Agents
In package.json around lines 38 to 39, the TypeDoc flags are invalid: remove the
unsupported "--emit none" and stop passing a .ts glob to "--includes"; instead
point "--includes" at a docs/includes directory (or omit it) and rely on
TypeDoc's --out for HTML and --json (or --json <file>) for JSON output so the
docs and spec.json are actually generated. Ensure --includes points to a
directory containing markdown if you need extras, or remove it to let TypeDoc
discover sources from the entryPoints.
| "engines": { | ||
| "node": ">=18.0.0" | ||
| }, |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Verify Node.js version requirement consistency across the monorepo.
The Node.js engine requirement is set to >=18.0.0. Ensure this aligns with other configuration files in the monorepo (CI workflows, other package.json files, etc.) to maintain consistency.
🏁 Script executed:
#!/bin/bash
# Description: Check for Node.js version consistency across the monorepo
# Expected: All Node.js version requirements should be consistent
echo "=== Checking Node.js engine requirements ==="
fd package.json --exec grep -l "engines" {} \; | xargs grep -A3 "engines"
echo -e "\n=== Checking GitHub workflows for Node.js versions ==="
fd -e yml -e yaml . .github/workflows | xargs grep -l "node" | xargs grep -A3 -B3 "node.*version"
echo -e "\n=== Checking other Node.js version references ==="
rg -n "node.*version|nodejs.*version" --type json --type yaml --type ymlLength of output: 2565
🏁 Script executed:
#!/bin/bash
# Verify .nvmrc version and inspect the CI matrix for Node.js versions
echo "=== Locating .nvmrc files ==="
fd .nvmrc
echo -e "\n=== .nvmrc contents ==="
fd .nvmrc --exec cat {} \;
echo -e "\n=== CI workflow (node matrix) excerpt ==="
sed -n '1,200p' .github/workflows/CI.ymlLength of output: 1597
Node.js Version Consistency & Missing .nvmrc
All package.json engine entries require Node >= 18.0.0 and your CI jobs cover Node 18 and 22, with the browser build/test using Node 20—all of which satisfy that requirement. However, your release workflows reference a .nvmrc file that doesn’t exist, which will break those jobs.
Please address the following:
- Add a root-level
.nvmrc(e.g. containing18) to pin the release workflows
• OR update.github/workflows/release-test.yml.github/workflows/release.yml
to usenode-version: "18"(or a matrix variable) instead ofnode-version-file: ".nvmrc".
🤖 Prompt for AI Agents
In packages/core/package.json around lines 32 to 34 the engines field requires
Node >=18.0.0 but your release workflows reference a missing root-level .nvmrc
which will break releases; either add a root .nvmrc file containing the desired
Node major version (e.g., "18") at the repository root, OR edit
.github/workflows/release-test.yml and .github/workflows/release.yml to replace
node-version-file: ".nvmrc" with an explicit node-version: "18" (or a workflow
matrix variable) so the workflows no longer depend on a non-existent file.
| "build": "run-s clean format build:*", | ||
| "build:main": "tsc -p tsconfig.json", | ||
| "build:module": "tsc -p tsconfig.module.json", | ||
| "build:umd": "webpack --mode=production", |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Verify build script execution order and dependencies.
The build script uses run-s (npm-run-all sequential) to execute clean, format, and build tasks. Ensure that the TypeScript configurations (tsconfig.json and tsconfig.module.json) referenced by build:main and build:module exist in the packages/core directory.
🏁 Script executed:
#!/bin/bash
# Description: Verify TypeScript configurations exist for the build scripts
# Expected: Both tsconfig.json and tsconfig.module.json should exist in packages/core
echo "=== Checking TypeScript configuration files in packages/core ==="
ls -la packages/core/tsconfig*.json
echo -e "\n=== Verifying build script dependencies are available ==="
cd packages/core && npm list run-s npm-run-all 2>/dev/null || echo "run-s/npm-run-all may need to be installed"Length of output: 710
🏁 Script executed:
#!/bin/bash
# Description: Verify that npm-run-all (providing run-s) is declared at the repo root
echo "=== Searching for npm-run-all in root package.json ==="
grep -n '"npm-run-all"' package.json || echo "npm-run-all not found in root package.json"
echo -e "\n=== Searching for run-s in root package.json scripts (optional) ==="
grep -n '"run-s"' package.json || echo "run-s not referenced in root package.json"Length of output: 466
🏁 Script executed:
#!/bin/bash
# Description: Verify if the monorepo uses npm workspaces to hoist devDependencies like npm-run-all
echo "=== Checking for npm workspaces configuration in root package.json ==="
grep -n '"workspaces"' -A5 package.json || echo "No workspaces field found in root package.json"Length of output: 295
Ensure npm-run-all (run-s) is available in packages/core
The TypeScript configs exist, but because there are no npm workspaces, the root-level npm-run-all devDependency isn’t hoisted into packages/core. As a result, the run-s clean format build:* step will fail.
• Add "npm-run-all" to packages/core/package.json devDependencies, e.g.:
"devDependencies": {
+ "npm-run-all": "^4.1.5",
…
}• Or configure npm workspaces at the repo root so root devDependencies are hoisted.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "build": "run-s clean format build:*", | |
| "build:main": "tsc -p tsconfig.json", | |
| "build:module": "tsc -p tsconfig.module.json", | |
| "build:umd": "webpack --mode=production", | |
| // packages/core/package.json | |
| { | |
| // … other fields … | |
| "devDependencies": { | |
| "npm-run-all": "^4.1.5", | |
| // … any existing devDependencies … | |
| }, | |
| "scripts": { | |
| "build": "run-s clean format build:*", | |
| "build:main": "tsc -p tsconfig.json", | |
| "build:module": "tsc -p tsconfig.module.json", | |
| "build:umd": "webpack --mode=production" | |
| } | |
| // … any other fields … | |
| } |
🤖 Prompt for AI Agents
In packages/core/package.json around lines 43 to 46 the "build" script uses
run-s (from npm-run-all) but that package is not available inside packages/core
because devDependencies are not hoisted without workspaces; add "npm-run-all" to
packages/core's devDependencies (or enable npm workspaces at the repo root so
root devDependencies are hoisted) and run install so the run-s command is
available locally; alternatively replace the composite script with a
node/npm-native solution (e.g., separate scripts or npm-run-all installed
globally in CI) if you prefer not to add the dependency.
| "include": ["src", "tests/types"], | ||
| "exclude": ["node_modules/**/*.ts"], |
There was a problem hiding this comment.
Fix TS6059: files outside rootDir due to include + rootDir mismatch
Including "tests/types" while setting "rootDir": "src" will cause TypeScript error TS6059 (“File is not under 'rootDir'”) during builds. It can also unintentionally emit declarations for test files if you expand rootDir.
Recommended fix: keep build tsconfig focused on src only, and move type test checking to a separate, noEmit tsconfig.
Apply this diff:
- "include": ["src", "tests/types"],
+ "include": ["src"],Optionally add a new packages/core/tsconfig.types.json to type-check tests without emitting:
{
"extends": "./tsconfig.json",
"include": ["tests/types"],
"compilerOptions": {
"noEmit": true,
"rootDir": "."
}
}You can then add an Nx target (e.g., "types") to run tsc -p packages/core/tsconfig.types.json in CI.
Also applies to: 9-9
🤖 Prompt for AI Agents
In packages/core/tsconfig.json around lines 2-3, the current include of
"tests/types" conflicts with "rootDir": "src" and triggers TS6059; remove
"tests/types" from the build tsconfig's "include" so the build-only config only
covers src, and add a separate tsconfig (e.g.,
packages/core/tsconfig.types.json) that extends the base, includes
["tests/types"], sets "noEmit": true and "rootDir": "." to type-check test types
without emitting; optionally add an Nx/CI target to run tsc -p
packages/core/tsconfig.types.json for CI type checks.
| "compilerOptions": { | ||
| "outDir": "dist/module", | ||
| "target": "ES2020", | ||
| "module": "ES2020" | ||
| } |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Verify package.json exports/entry points align with dist/module.
Ensure packages/core/package.json "module" and/or conditional "exports" point to dist/module for ESM and dist/main for CJS, matching Nx build outputs.
Expected (illustrative):
- main -> dist/main/index.js (CJS)
- module -> dist/module/index.js (ESM)
- exports -> conditional map for . and subpaths to both main/module builds
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "packages/core/package.json exports and entry points:"
cat packages/core/package.json | jq '{name, main, module, types, exports}'Length of output: 395
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "packages/core/package.json exports and entry points:"
jq '. | {name: .name, main: .main, module: .module, types: .types, exports: .exports}' packages/core/package.jsonLength of output: 404
Add conditional exports field to align ESM/CJS entry points
The main and module fields are correctly pointing to dist/main/index.js and dist/module/index.js, but the exports field is missing—Node.js consumers will not be able to resolve the appropriate format without it. Please update packages/core/package.json to include a conditional exports map:
• File: packages/core/package.json
• Add under "module": "dist/module/index.js", (or at the end of "types") the following block:
"types": "dist/module/index.d.ts",
+ "exports": {
+ ".": {
+ "import": "./dist/module/index.js",
+ "require": "./dist/main/index.js",
+ "types": "./dist/module/index.d.ts"
+ },
+ "./package.json": "./package.json"
+ }This ensures:
- ESM imports (
import ... from "@deepgram/sdk") resolve todist/module/index.js. - CJS requires (
require("@deepgram/sdk")) resolve todist/main/index.js. - TypeScript tooling picks up the correct
.d.tsfile.
Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In packages/core/package.json (add the change near where "module":
"dist/module/index.js" is declared or after the "types" entry), add a
conditional "exports" map that points "." to an object with "import" =>
"dist/module/index.js", "require" => "dist/main/index.js", and "types" =>
"./dist/types/index.d.ts" (also include a "./package.json" export if needed);
update or ensure "main" and "module" remain set to "dist/main/index.js" and
"dist/module/index.js" respectively, and bump/add "types" to point at the
bundled d.ts so Node and TypeScript resolve ESM vs CJS correctly.
| #!/bin/bash | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Harden script with strict mode
Add set -euo pipefail to fail fast on errors, unset vars, and pipe failures.
Apply this diff:
#!/bin/bash
+
+set -euo pipefail📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| #!/bin/bash | |
| #!/bin/bash | |
| set -euo pipefail |
🤖 Prompt for AI Agents
In test-release.sh around lines 1 to 2, the script lacks robust shell strict
mode; add a line immediately after the shebang to enable "set -euo pipefail"
(and optionally set IFS=$'\n\t' if desired) so the script exits on errors,
treats unset variables as failures, and surfaces pipeline failures; ensure the
new line is placed right after "#!/bin/bash" and commit the change.
| echo "📋 Current Configuration:" | ||
| echo " - Draft releases: $(cat .release-please-config.json | jq -r .draft)" | ||
| echo " - Package: $(cat .release-please-manifest.json | jq -r '."packages/core"')" | ||
| echo " - Core package name: $(cat packages/core/package.json | jq -r .name)" | ||
| echo "" |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Avoid UUOC and guard jq presence
Use jq directly on files and fail early if jq is missing to provide clearer guidance.
Apply this diff:
-echo "📋 Current Configuration:"
-echo " - Draft releases: $(cat .release-please-config.json | jq -r .draft)"
-echo " - Package: $(cat .release-please-manifest.json | jq -r '."packages/core"')"
-echo " - Core package name: $(cat packages/core/package.json | jq -r .name)"
+echo "📋 Current Configuration:"
+if ! command -v jq >/dev/null 2>&1; then
+ echo "❌ Error: jq is required. Install via 'pnpm add -g jq' or your package manager."
+ exit 1
+fi
+echo " - Draft releases: $(jq -r .draft .release-please-config.json)"
+echo " - Package: $(jq -r '."packages/core"' .release-please-manifest.json)"
+echo " - Core package name: $(jq -r .name packages/core/package.json)"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| echo "📋 Current Configuration:" | |
| echo " - Draft releases: $(cat .release-please-config.json | jq -r .draft)" | |
| echo " - Package: $(cat .release-please-manifest.json | jq -r '."packages/core"')" | |
| echo " - Core package name: $(cat packages/core/package.json | jq -r .name)" | |
| echo "" | |
| echo "📋 Current Configuration:" | |
| if ! command -v jq >/dev/null 2>&1; then | |
| echo "❌ Error: jq is required. Install via 'pnpm add -g jq' or your package manager." | |
| exit 1 | |
| fi | |
| echo " - Draft releases: $(jq -r .draft .release-please-config.json)" | |
| echo " - Package: $(jq -r '."packages/core"' .release-please-manifest.json)" | |
| echo " - Core package name: $(jq -r .name packages/core/package.json)" | |
| echo "" |
🤖 Prompt for AI Agents
In test-release.sh around lines 12 to 16: the script uses UUOC (cat piped to jq)
and doesn't check for jq availability; update these lines to invoke jq with file
arguments (e.g. jq -r .draft .release-please-config.json) instead of piping from
cat, and add an early guard that checks for jq in PATH (exit non‑zero with a
helpful message if missing) before any jq calls so the script fails fast with
clear guidance.
| echo "" | ||
|
|
||
| echo "🧪 Testing package structure..." | ||
| cd packages/core |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Check cd success (ShellCheck SC2164)
Ensure the script exits if the directory doesn’t exist to avoid cascading errors.
Apply this diff:
-cd packages/core
+cd packages/core || { echo "❌ Error: packages/core not found"; exit 1; }📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| cd packages/core | |
| cd packages/core || { echo "❌ Error: packages/core not found"; exit 1; } |
🧰 Tools
🪛 Shellcheck (0.10.0)
[warning] 28-28: Use 'cd ... || exit' or 'cd ... || return' in case cd fails.
(SC2164)
🤖 Prompt for AI Agents
In test-release.sh around line 28, the script does "cd packages/core" without
checking success; change it to abort if the directory change fails (e.g., use
"cd packages/core || exit 1" or "cd packages/core || { echo 'Failed to cd to
packages/core' >&2; exit 1; }") so the script stops immediately when the
directory doesn't exist.
1 participant
Proposed changes
This PR converts the Deepgram JavaScript SDK from a single-package repository to an Nx monorepo structure in preparation for upcoming package architecture changes. The existing
@deepgram/sdkis moved topackages/core/while maintaining full backward compatibility and identical functionality.Key changes:
packages/core/Safe deployment: This PR includes temporary release-please skip flags and should be merged with
[skip release]to prevent accidental deployments during infrastructure migration.Types of changes
What types of changes does your code introduce to the community JavaScript SDK?
Put an
xin the boxes that applyChecklist
Put an
xin the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.Further comments
Why Nx monorepo?
This migration prepares the SDK for upcoming package architecture changes where we'll split functionality into multiple focused packages (e.g., separate auth, streaming, batch processing packages). Nx provides excellent tooling for managing multi-package dependencies, builds, and releases.
Backward compatibility:
@deepgram/sdkpackage name and API remain identicalMigration safety:
Next steps after merge:
Summary by CodeRabbit