mirror of
https://github.com/lancedb/lancedb.git
synced 2026-09-01 02:58:36 +00:00
Will Jones
a87cada90e
The bindings are built, installed and published with pnpm everywhere,
but a parallel npm dependency graph was still being maintained beside
it. This removes it, raises the supported Node floor to the versions we
actually test, and gives Dependabot the npm coverage it was missing.
## Dropping npm
`nodejs/package-lock.json` was regenerated by `ci/update_lockfiles.sh`
on every release commit and read by nothing — no workflow runs `npm ci`
or `npm install` in `nodejs/`, and npm never publishes a lockfile in a
package tarball. It could not even agree with the real install, since
npm does not see pnpm's `overrides`. Because GitHub's dependency graph
parses `package-lock.json`, it was also reporting vulnerabilities for a
tree we neither install nor ship.
`docs/package.json`, `docs/package-lock.json` and `docs/tsconfig.json`
go too. They depend on `file:../node` and
`file:../node/node_modules/apache-arrow` — the `node/` directory was
removed long ago — the tsconfig compiles `src/*.ts` where no TypeScript
files exist, and nothing installs any of it. `docs.yml` only referenced
the lockfile to configure an npm cache for an install it never ran.
Two `workflow_dispatch` workflows for regenerating those lockfiles are
removed as well. Both were already broken: they `uses:` composite
actions at `.github/workflows/update_package_lock{,_nodejs}` that do not
exist, so dispatching either failed immediately.
The remaining `npx` calls become direct `node_modules/.bin/...`
invocations. These were already running locally installed binaries
rather than resolving anything, but naming the binary removes the npm
CLI from the loop and does not depend on which Node version is active.
`dev.yml`'s commitlint check was the last place doing real npm
dependency resolution — an unpinned `npm install
@commitlint/config-conventional` that also bypassed the
`minimumReleaseAge` hold configured for `nodejs/` — and is now a pinned
`pnpm dlx`.
## Node support
Node 18 and 20 both reached end-of-life, in April 2025 and April 2026.
The matrix moves to 22, 24 and 26, and `engines` rises from `>= 18` to
`>= 22` so the declared floor is one the matrix actually covers. Node 22
is LTS until April 2027; 24 is LTS; 26 is Current and becomes LTS in
October 2026.
This also removes the reason the workflows reached for `npx` in the
first place: pnpm 11 requires Node >= 22.13, which every matrix version
now satisfies.
The prebuilt-binary smoke test in `npm-publish.yml` moves from Node 20
to Node 22 — the floor, where a napi ABI problem would surface first —
rather than fanning out across all three, to keep the publish matrix
from tripling.
## Dependabot
There were no npm-ecosystem entries at all, which is why the advisories
behind #4073 went unnoticed. Both pnpm lockfiles are now watched —
`nodejs/` and `nodejs/examples/`, which is a separate install — using
the same `lockfile-only` strategy as the existing cargo and pip entries,
so version ranges in `package.json` are left alone.
## Pre-commit biome
The hook ran `npx @biomejs/biome@1.8.3` while `nodejs/package.json`
resolved 1.9.4. The two disagree about formatting, so the hook rejected
code that `pnpm lint` accepts, and failed on unmodified `main` for
anyone touching `nodejs/`. It now uses the pnpm-managed biome, which
fixes the drift with no source changes.
## Testing
`dev.yml`'s commitlint job does not check out the repo, so it runs in an
empty workspace, and I could not verify `pnpm/action-setup` there
locally. It triggers on `pull_request_target`, so this PR exercises it
directly — worth confirming green before merge. I did verify the `pnpm
dlx` invocation itself locally: it accepts a conventional title and
rejects a non-conventional one with exit 1.
Node 26 is new enough that the examples job may surface gaps in prebuilt
native binaries (`onnxruntime-node`, `sharp`) before their maintainers
publish for it.
## Not included
`nodejs/examples/` still pins `sharp: "0.33.5"` and has its own audit
findings. Raising the Node floor unblocks that work — sharp 0.35
requires Node >= 20.9, which the matrix now satisfies — but it is a
dependency bump rather than tooling cleanup, so it is left separate.
## Breaking changes
`@lancedb/lancedb` now requires Node >= 22; previously >= 18. The
`@types/node` peer range moves from `>=18` to `>=22` to match. Users on
Node 18 or 20 must upgrade their runtime; both have been end-of-life for
some time. Existing installs are unaffected, since `engines` is only
checked on install.
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
93 lines
2.4 KiB
Markdown
93 lines
2.4 KiB
Markdown
# LanceDB Documentation
|
|
|
|
LanceDB docs are available at [docs.lancedb.com](https://docs.lancedb.com).
|
|
|
|
The SDK docs are built and deployed automatically by [Github Actions](../.github/workflows/docs.yml)
|
|
whenever a commit is pushed to the `main` branch. So it is possible for the docs to show
|
|
unreleased features.
|
|
|
|
## Building the docs
|
|
|
|
### Setup
|
|
1. Install LanceDB Python. See setup in [Python contributing guide](../python/CONTRIBUTING.md).
|
|
Run `make develop` to install the Python package.
|
|
2. Install documentation dependencies. From LanceDB repo root: `pip install -r docs/requirements.txt`
|
|
|
|
### Preview the docs
|
|
|
|
```shell
|
|
cd docs
|
|
mkdocs serve
|
|
```
|
|
|
|
If you want to just generate the HTML files:
|
|
|
|
```shell
|
|
PYTHONPATH=. mkdocs build -f docs/mkdocs.yml
|
|
```
|
|
|
|
If successful, you should see a `docs/site` directory that you can verify locally.
|
|
|
|
## Adding examples
|
|
|
|
To make sure examples are correct, we put examples in test files so they can be
|
|
run as part of our test suites.
|
|
|
|
You can see the tests are at:
|
|
|
|
* Python: `python/python/tests/docs`
|
|
* Typescript: `nodejs/examples/`
|
|
|
|
### Checking python examples
|
|
|
|
```shell
|
|
cd python
|
|
pytest -vv python/tests/docs
|
|
```
|
|
|
|
### Checking typescript examples
|
|
|
|
The examples depend on `@lancedb/lancedb` at `file:../dist`, so the package must be
|
|
built before running the tests. This uses pnpm; see the
|
|
[Typescript contributing guide](../nodejs/CONTRIBUTING.md) for the toolchain setup.
|
|
|
|
```shell
|
|
pushd nodejs
|
|
pnpm install
|
|
pnpm build
|
|
popd
|
|
```
|
|
|
|
Then you can run the examples by going to the `nodejs/examples` directory, which is a
|
|
separate pnpm package with its own lockfile:
|
|
|
|
```shell
|
|
pushd nodejs/examples
|
|
pnpm install
|
|
pnpm test
|
|
popd
|
|
```
|
|
|
|
## API documentation
|
|
|
|
### Python
|
|
|
|
The Python API documentation is organized based on the file `docs/src/python/python.md`.
|
|
We manually add entries there so we can control the organization of the reference page.
|
|
**However, this means any new types must be manually added to the file.** No additional
|
|
steps are needed to generate the API documentation.
|
|
|
|
### Typescript
|
|
|
|
The typescript API documentation is generated from the typescript source code using [typedoc](https://typedoc.org/).
|
|
|
|
When new APIs are added, you must manually re-run the typedoc command to update the API documentation.
|
|
The new files should be checked into the repository.
|
|
|
|
```shell
|
|
pushd nodejs
|
|
# `pnpm docs` would invoke pnpm's built-in `docs` command, not the script.
|
|
pnpm run docs
|
|
popd
|
|
```
|