Contributing to code ↗

    git clone https://github.com/your-username/name-of-forked-repo.git

    # For instance, for LangChain:
    git clone https://github.com/parrot123/langchainjs.git

    # For LangGraph:
    git clone https://github.com/parrot123/langgraphjs.git
    ```

```bash
    # Inside your repo, install dependencies
    pnpm install
    # Create a build for all packages to resolve workspace dependencies
    pnpm build
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Create a branch"></span>
Create a new branch for your fix. This helps keep your changes organized and makes it easier to submit a pull request later.

```bash
    git checkout -b your-username/short-bugfix-name
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Write failing tests"></span>
Add [unit tests](#test-writing-guidelines) that will fail without your fix. This allows us to verify the bug is resolved and prevents regressions
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Make your changes"></span>
Fix the bug while following our [code quality standards](#code-quality-standards). Make the **minimal change necessary** to resolve the issue. We strongly encourage contributors to comment on the issue before they start coding. For example:

> *"I'd like to work on this. My intended approach would be to \[...brief description...]. Does this align with maintainer expectations?"*

A 30-second comment often prevents wasted effort if your initial approach is wrong.
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Run build"></span>
Run the build command to ensure the package still builds properly

```bash
    pnpm build
    # or build a specific workspace package
    pnpm --filter @langchain/core build
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Verify the fix"></span>
Ensure that tests pass and no regressions are introduced. Ensure all tests pass locally before submitting your PR

```bash
    pnpm lint
    pnpm test

    # For bugfixes involving integrations, also run:
    pnpm test:int

    # Or run tests in a specific workspace package
    cd libs/langchain-core
    pnpm test
    pnpm lint

    # Or run tests for a specific package from the root of the repo
    pnpm --filter @langchain/core test
    pnpm --filter @langchain/core lint
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Document the change"></span>
Update docstrings and/or inline comments if behavior changes
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Submit a pull request"></span>
Follow the PR template provided. If applicable, reference the issue you're fixing using a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) (e.g. `Fixes #ISSUE_NUMBER`) so that the issue is automatically closed when your PR is merged.
  <span class="step-end"></span>
<span class="steps-end"></span>

### Full development setup

For ongoing development or larger contributions:

1. Review our [contribution guidelines](#contribution-guidelines) for features, bugfixes, and integrations
2. Set up your environment following our [setup guide](#development-environment) below
3. Understand the [repository structure](#repository-structure) and package organization
4. Learn our [development workflow](#development-workflow) including testing and linting

***

## Contribution guidelines

Before you start contributing to LangChain projects, take a moment to think about why you want to. If your only goal is to add a "first contribution" to your resume (or if you're just looking for a quick win) you might be better off doing a boot-camp or an online tutorial.

Contributing to open source projects takes time and effort, but it can also help you become a better developer and learn new skills. However, it's important to know that it might be harder and slower than following a training course. That said, contributing to open source is worth it if you're willing to take the time to do things well!

### Backwards compatibility

<span class="callout-start" data-callout-type="warning"></span>
  Breaking changes to public APIs are not allowed except for critical security fixes.

  See our [versioning policy](/oss/javascript/versioning) for details on major version releases.
<span class="callout-end"></span>

Maintain compatibility via:

<AccordionGroup>
  <Accordion title="Stable interfaces">
**Always preserve**:

* Function signatures and parameter names
* Class interfaces and method names
* Return value structure and types
* Import paths for public APIs
  </Accordion>

  <Accordion title="Safe changes">
**Acceptable modifications**:

* Adding new optional parameters/type parameters

* Adding new methods to classes

* Improving performance without changing behavior

* Adding new modules or functions
  </Accordion>

  <Accordion title="Before making changes">
* **Would this break existing user code?**

* Check if your target is public

* Are there existing usage patterns in tests?
  </Accordion>
</AccordionGroup>

### New features

We aim to keep the bar high for new features. We generally don't accept new core abstractions from outside contributors without an existing issue that demonstrates an acute need for them. This also applies to changes to infrastructure and dependencies.

In general, feature contribution requirements include:

<span class="steps-start"></span>
  <span class="step-marker" data-step-title="Design discussion"></span>
Open an issue describing:

* The problem you're solving
* Proposed API design
* Expected usage patterns
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Implementation"></span>
* Follow existing code patterns
* Include comprehensive tests and documentation
* Consider security implications
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Integration considerations"></span>
* How does this interact with existing features?
* Are there performance implications?
* Does this introduce new dependencies?

We will reject features that are likely to lead to security vulnerabilities or reports.
  <span class="step-end"></span>
<span class="steps-end"></span>

### Security guidelines

<span class="callout-start" data-callout-type="warning"></span>
  Security is paramount. Never introduce vulnerabilities or unsafe patterns.
<span class="callout-end"></span>

Security checklist:

<AccordionGroup>
  <Accordion title="Input validation">
* Validate and sanitize all user inputs

* Properly escape data in templates and queries

* Never use `eval()`, as this can lead to arbitrary code execution vulnerabilities
  </Accordion>

  <Accordion title="Error handling">
* Use specific exception types
* Don't expose sensitive information in error messages
* Implement proper resource cleanup
  </Accordion>

  <Accordion title="Dependencies">
* Avoid adding hard dependencies
* Keep optional dependencies minimal
* Review third-party packages for security issues
  </Accordion>
</AccordionGroup>

***

## Development environment

<span class="callout-start" data-callout-type="warning"></span>
  Our JS/TS projects uses [`pnpm`](https://pnpm.io/) for dependency management. Make sure you have the latest version installed, or run `corepack enable` (on Node 24+) to setup the required pnpm version.
<span class="callout-end"></span>

<span class="callout-start" data-callout-type="info"></span>
  We strive to keep setup consistent across all JS/TS packages. From the repo root, run:

  ```bash
  pnpm install
  pnpm --filter {package-name} test  # Verify tests pass before starting development

# Run the entire test suite
pnpm test

# Or run a specific test file
pnpm test src/tests/FILENAME_BEING_TESTED.test.ts

# Or run a specific test function
pnpm test -t "the test that should be run"

pnpm test:int

    function processDocuments(
        docs: Document[],
        processor: DocumentProcessor,
        batchSize: number = 100
    ): ProcessingResult {
        // ...
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Documentation"></span>
**Required**: [JSDocs](https://jsdoc.app/about-getting-started) for all exported functions and interfaces

```typescript
    /**
     * Document processing instance.
     */
    interface FooDocumentProcessor {
        /**
         * Process documents in batches.
         *
         * @param docs - List of documents to process.
         * @returns Processing results with success/failure counts.
         */
        process(docs: Document[]): ProcessingResult;
    }

    /**
     * Process documents in batches.
     *
     * @param docs - List of documents to process.
     * @param processor - Document processing instance.
     * @param batchSize - Number of documents per batch.
     * @returns Processing results with success/failure counts.
     */
    export function processDocuments(
        docs: Document[],
        processor: DocumentProcessor,
        batchSize: number = 100
    ): ProcessingResult {
        // ...
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Code style"></span>
**Automated**: Formatting and linting:

```bash
    pnpm lint    # Check style and types
    pnpm format  # Apply formatting
    ```

**Standards**:

* Descriptive variable names
* Break up complex functions (aim for fewer than 20 lines)
* Follow existing patterns in the codebase
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

***

### Test writing guidelines

In order to write effective tests, there's a few good practices to follow:

* Encapsulate the test in a `describe` block that describes the component being tested
* Use natural language to describe the test name
* Be exhaustive with assertions
* Only use snapshots for reasonably sized data objects

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Unit tests"></span>
```typescript
    describe("DocumentProcessor", () => {
        it("Should handle empty document list", () => {
            const processor = new DocumentProcessor();
            const result = processor.process([]);

            expect(result.success).toBe(true);
            expect(result.processedCount).toBe(0);
            expect(result.errors).toHaveLength(0);
        });
    });
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Integration tests"></span>
```typescript
    describe("ChatOpenAI", () => {
        it("Should test with real API", () => {
            const chat = new ChatOpenAI();
            const response = chat.invoke("Hello");
        });
    });
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Mock usage"></span>
```typescript
    describe("APIService", () => {
        it("Should call with retry", () => {
            const mockClient = new MockClient();
            const service = new APIService(client: mockClient);
            const result = service.callWithRetry();
        });
    });
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Submitting your PR

Once your tests pass and code meets quality standards:

1. Push your branch and open a pull request
2. Follow the provided PR template
3. Reference related issues using a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) (e.g., `Fixes #123`)
4. Wait for CI checks to complete

<span class="callout-start" data-callout-type="warning"></span>
  Address CI failures promptly. Maintainers may close PRs that do not pass CI within a reasonable timeframe.
<span class="callout-end"></span>

## Getting help

Our goal is to have the most accessible developer setup possible. Should you experience any difficulty getting setup, please ask in the [community slack](https://www.langchain.com/join-community) or open a [forum post](https://forum.langchain.com/).

<span class="callout-start" data-callout-type="check"></span>
  You're now ready to contribute high-quality code to LangChain!
<span class="callout-end"></span>

***


  <span class="callout-start" data-callout-type="note"></span>
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/contributing/code.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  <span class="callout-end"></span>

  <span class="callout-start" data-callout-type="note"></span>
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  <span class="callout-end"></span>