Plaid Pattern: a sample personal finance manager for linking items and transactions

A reference implementation, labelled as one

Plaid Pattern is a sample Personal Finance Manager application demonstrating an end-to-end Plaid integration, focused on linking items and fetching transaction data. The framing matters more here than in most sample projects, because the README states plainly that Plaid Pattern apps are provided for illustrative purposes and are not meant to be run as production applications. That is a licence, a promise and a warning in one sentence. The licence is MIT, the promise is that the code shows the intended shape of an integration, and the warning is that access token handling, session management and deployment are not finished. The audience is a developer building against the Plaid API who wants to see the whole path from a user clicking Link to a transaction row appearing in a dashboard, rather than a sequence of isolated API calls.

Link, OAuth and update mode on the client

The client is a React single page application on Vite, written in TypeScript, and it runs on port 3001 by default. What it presents is a basic Link workflow, including an implementation of OAuth and a demonstration of Link update mode, which is the flow for repairing or changing an existing item rather than creating a new one. The screens are deliberately plain: a user's net worth, categorized spending, and a simple dashboard listing linked accounts and transactions. There is also an admin view on the local admin path, which shows all users and lets a developer remove one, which is a development convenience and another sign of the sample's intent. Every HTTP call the client makes to the server is defined in one file, the api service, apart from the websocket listeners, so the surface between the two halves is easy to read.

Webhooks in, websocket messages out

The data flow for a linked account is the part worth understanding before anything else. The server is configured to send a message over a websocket whenever it receives a webhook from Plaid, and on the client side the websocket listeners in the sockets component wait for those messages and update the data in real time. The browser therefore never talks to Plaid directly, and the webhook endpoint is never exposed to the browser, which is the arrangement a production product also needs. The cost of the arrangement is that the server must be reachable from the public internet, which is why ngrok is a hard requirement in the README's setup steps: it exposes the server so that Plaid can deliver webhooks. The backend listens on port 5001 and the tunnel points at that port. Any evaluation of this sample should include the question of how you would terminate TLS and authenticate webhooks in your own environment.

Tying your users to Plaid items yourself

The server is JavaScript on Node.js with Express, talking to Plaid through the Plaid Node SDK and to the database through node-postgres. The README makes a point that costs real time to discover on your own: Plaid does not have a user data object for tying multiple items together, so it is up to application developers to define that relationship. The sample demonstrates it in the root items route, used to store new items, and in the users routes. In other words, the item and its access token belong to a row you own, and the mapping from your user to several items is application data that Plaid does not keep for you. The README also notes that the concepts shown here apply whatever language your backend is written in, which is a hint that this is the part most teams copy rather than the React code.

Stopping a user from linking the same bank twice

The second key concept in the server is item duplication, and the README treats it as a business decision rather than a technical detail. By default, Plaid Link will let a user link to the same institution multiple times, and it is entirely possible for a user to end up with several items linked to the same financial institution. The README states that some developers prefer to disallow duplicate account linkages, because duplicate connections still come at an additional cost, and that in practice you probably want to prevent this. The approach it recommends is the simplest one: check the institution id of a newly created item before performing the token exchange. That ordering is the point. The check has to happen before the exchange, because after the exchange the access token exists and the cost has been incurred, so a check that runs later only cleans up after the fact.

Running ngrok, the backend and the frontend in three terminals

The setup steps are explicit about the environment. Node.js 20.19 or newer, or 22.12 and up, is required, together with PostgreSQL 16 or higher, Plaid API keys from a free Sandbox account, and ngrok with an authtoken. On Linux and WSL the README warns that the nodejs package in the Ubuntu default repositories is older than the required version, so Node has to come from nvm or NodeSource. Windows users are pointed at WSL. The repository is cloned and the environment file is created from the template, which is where the Plaid keys and the Postgres password go:

The tunnel, the backend and the frontend in three terminals

The setup steps are explicit about the environment. Node.js 20.19 or newer, or 22.12 and up, is required, together with PostgreSQL 16 or higher, Plaid API keys from a free Sandbox account, and ngrok with an authtoken. On Linux and WSL the README warns that the nodejs package in the Ubuntu default repositories is older than the required version, so Node has to come from nvm or NodeSource. Windows users are pointed at WSL. The repository is cloned and the environment file is created from the template, which is where the Plaid keys and the Postgres password go:

    git clone https://github.com/plaid/pattern.git
    cd pattern

    cp .env.template .env

Dependencies for both halves are installed with a single script, and the database is created and initialised from the SQL file in the database directory:

    npm run install:all

    createuser -s postgres  # skip if the postgres role already exists
    npm run db:create

On Linux and WSL the postgres role already exists but only accepts local connections from the postgres operating system user, so the README gives a different route: set a password for the role that matches the value in the environment file, then create the database over TCP. Once the database exists, three processes run in separate terminals, and only after the tunnel is up do the webhooks have a path back to the server:

    ngrok http 5001   # exposes the server for Plaid webhooks
    npm run server    # starts the backend on port 5001
    npm run client    # starts the frontend on port 3001

The client is then opened on the local port 3001. A Makefile offers the same operations as targets, including an interactive psql session, and it refuses to run the server or client targets if the environment file is missing.

A 2019 release line and the other sample apps

The maintenance picture is worth checking before you copy from this code. The visible tags are v1.0.5 on 2019-09-03, v1.0.4 on 2019-08-28 and v1.0.3 on 2019-07-23, the manifest in the repository root carries version 1.0.7, and the last push was on 2026-10-16. So the repository keeps receiving work while the tagged releases stopped in 2019, and the sample is pointed at the Plaid Transactions API. Plaid publishes a family of related samples, and the differences between them are a matter of which API each demonstrates: this one covers Transactions, the account funding app covers the Auth, Balance and Identity APIs, the Transfer Quickstart app covers the Transfer API and is described as up to date, while the older Pattern Transfer App is explicitly deprecated in favour of the Quickstart. If your goal is Transfers, the Quickstart is the one to read, and the deprecation of its sibling is a good reason not to start here.

Editorial conclusion

Plaid Pattern fits a developer who needs a working reference for the Plaid item, Link and transaction flow, and who will rebuild the parts that matter rather than ship them. It does not fit a production deployment, since the README says so directly and the code stores access tokens in a plain PostgreSQL table. Verify first that your Plaid environment is the Sandbox and that your Node and PostgreSQL versions match the stated requirements, then read the item and user routes in the server, because the association between your users and Plaid items is the part the sample deliberately leaves to you.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. plaid/pattern on GitHub
4. README
5. Releases