TypeScript and JavaScript
This guide is meant to provide specific instructions to get you producing index data in LSIF as quickly as possible for JavaScript and TypeScript codebases.
Automated indexing
We provide the docker images sourcegraph/lsif-node
and sourcegraph/src-cli
to make automating this process in your favorite CI framework as easy as possible. Note that the lsif-node
image bundles src-cli
so the second image may not be necessary.
Here's some examples in a couple popular frameworks, just substitute the indexer and upload commands with what works for your project locally:
GitHub Actions
jobs: lsif-node: # this line will prevent forks of this repo from uploading lsif indexes if: github.repository == '<insert your repo name>' runs-on: ubuntu-latest container: sourcegraph/lsif-node:latest steps: - uses: actions/checkout@v1 - name: Install dependencies run: npm install - name: Generate LSIF data run: lsif-tsc -p . - name: Upload LSIF data # this will upload to Sourcegraph.com, you may need to substitute a different command # by default, we ignore failures to avoid disrupting CI pipelines with non-critical errors. run: src lsif upload -github-token=${{ secrets.GITHUB_TOKEN }}
Note that if you need to install your dependencies in a custom container, you can use our containers as github actions. Try these steps instead:
jobs: lsif-node: # this line will prevent forks of this repo from uploading lsif indexes if: github.repository == '<insert your repo name>' runs-on: ubuntu-latest container: my-awesome-container steps: - uses: actions/checkout@v1 - name: Install dependencies run: <install dependencies> - name: Generate LSIF data uses: docker://sourcegraph/lsif-node:latest with: args: lsif-tsc -p . - name: Upload LSIF data uses: docker://sourcegraph/src-cli:latest with: # this will upload to Sourcegraph.com, you may need to substitute a different command # by default, we ignore failures to avoid disrupting CI pipelines with non-critical errors. args: lsif upload -github-token=${{ secrets.GITHUB_TOKEN }}
The following projects have example GitHub Action workflows to generate and upload LSIF indexes.
CircleCI
version: 2.1 jobs: lsif-node: docker: - image: sourcegraph/lsif-node:latest steps: - checkout - run: npm install - run: lsif-tsc -p . # this will upload to Sourcegraph.com, you may need to substitute a different command # by default, we ignore failures to avoid disrupting CI pipelines with non-critical errors. - run: src lsif upload -github-token=<<parameters.github-token>> workflows: lsif-node: jobs: - lsif-node
Note that if you need to install your dependencies in a custom container, may need to use CircleCI's caching features to share the build environment with our container. It may alternately be easier to add our tools to your container, but here's an example using caches:
jobs: install-deps: docker: - image: my-awesome-container steps: - checkout - <install dependencies> - save_cache: paths: - node_modules key: dependencies jobs: lsif-node: docker: - image: sourcegraph/lsif-node:latest steps: - checkout - restore_cache: keys: - dependencies - run: lsif-tsc -p . # this will upload to Sourcegraph.com, you may need to substitute a different command # by default, we ignore failures to avoid disrupting CI pipelines with non-critical errors. - run: src lsif upload -github-token=<<parameters.github-token>> workflows: lsif-node: jobs: - install-deps - lsif-node: requires: - install-deps
The following projects have example CircleCI configurations to generate and upload LSIF indexes.
Travis CI
services: - docker jobs: include: - stage: lsif-node # this will upload to Sourcegraph.com, you may need to substitute a different command # by default, we ignore failures to avoid disrupting CI pipelines with non-critical errors. script: - | docker run --rm -v $(pwd):/src -w /src sourcegraph/lsif-node:latest /bin/sh -c \ "lsif-tsc -p .; src lsif upload -github-token=$GITHUB_TOKEN"
The following projects have example Travis CI configurations to generate and upload LSIF indexes.
Manual indexing
Manual indexing is valuable as a proof of concept, however, it may be difficult to keep indexes up to date and enable cross repository navigation.
-
Install lsif-node with
npm install -g @sourcegraph/lsif-tsc
or your favorite method of installing npm packages. -
Install the Sourcegraph CLI with
curl -L https://sourcegraph.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src chmod +x /usr/local/bin/src
- macOS: replace
linux
withdarwin
in the URL - Windows: visit the CLI's repo for further instructions
- macOS: replace
-
cd
into your project's root (where the package.json/tsconfig.json) and run the following:# install your projects dependencies with npm or yarn npm install # for typescript projects lsif-tsc -p . # for javascript projects lsif-tsc **/*.js --allowJs --checkJs
NOTE: The
npm install
step is required to correctly typecheck the codebase and to enable cross-repo navigation.
If you are working with a mono-repo that contains different projects, you may use the above procedure in sub projects within the monorepo. For example, Project A is located in <repo root>/proja/
and Project B is located in <repo root>/projb/
. You just need to invoke lsif-tsc
and src lsif upload
in both ./proja
and ./projb
directories to generate and upload a precise code intelligence index for each project.
Check out the tool's documentation if you're having trouble getting lsif-tsc
to work. It accepts any options tsc
does, so it shouldn't be too hard to get it running on your project.
-
Upload the data to a Sourcegraph instance with
# for private instances src -endpoint=<your sourcegraph endpoint> lsif upload # for public instances src lsif upload -github-token=<your github token>
The upload command will provide a URL you can visit to see the upload's status, and when it's done you can visit the repo and check out the difference in code navigation quality!