https://github.com/couchbase-examples/typescript-quickstart
Entry level Couchbase Type Script tutorial/demo.
https://github.com/couchbase-examples/typescript-quickstart
Last synced: about 1 month ago
JSON representation
Entry level Couchbase Type Script tutorial/demo.
- Host: GitHub
- URL: https://github.com/couchbase-examples/typescript-quickstart
- Owner: couchbase-examples
- License: mit
- Created: 2024-01-09T08:28:23.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-08-13T07:51:44.000Z (8 months ago)
- Last Synced: 2025-08-13T09:25:03.298Z (8 months ago)
- Language: TypeScript
- Homepage:
- Size: 1.23 MB
- Stars: 0
- Watchers: 5
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Quickstart in Couchbase with TypeScript, Node JS SDK and Express
#### Build a REST API with TypeScript, Node JS SDK and Express
Often, the first step developers do after creating their database is to create a REST API that can perform Create, Read, Update, and Delete (CRUD) operations for that database. This repo is designed to teach you and give you a starter project (in TypeScript using Express) to generate such a REST API. After you have installed travel-sample bucket in your database, you can run this application which is a REST API with Swagger documentation so that you can learn:
1. How to create, read, update, and delete documents using [Key Value operations](https://docs.couchbase.com/nodejs-sdk/current/howtos/kv-operations.html) (KV operations). KV operations are unique to couchbase and provide super fast (think microseconds) queries.
2. How to write simple parametrized [SQL++ queries](https://docs.couchbase.com/nodejs-sdk/current/howtos/n1ql-queries-with-sdk.html) using the built-in travel-sample bucket.
Full documentation for the tutorial can be found on the [Couchbase Developer Portal](https://developer.couchbase.com/tutorial-quickstart-typescript).
If you are looking for a quickstart using Node JS, you can find it in this [repo](https://github.com/couchbase-examples/nodejs-quickstart).
## Prerequisites
To run this prebuilt project, you will need:
- [Couchbase Capella](https://www.couchbase.com/products/capella/) cluster with [travel-sample](https://docs.couchbase.com/nodejs-sdk/current/ref/travel-app-data-model.html) bucket loaded.
- To run this tutorial using a self managed Couchbase cluster, please refer to the [appendix](#running-self-managed-couchbase-cluster).
- [LTS Node.js Version](https://nodejs.org/en/download) installed on local machine.
- Basic knowledge of [JavaScript](https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/JavaScript_basics), [TypeScript](https://www.typescriptlang.org/) and [Express](https://expressjs.com/)
- Loading Travel Sample Bucket
If travel-sample is not loaded in your Capella cluster, you can load it by following the instructions for your Capella Cluster:
- [Load travel-sample bucket in Couchbase Capella](https://docs.couchbase.com/cloud/clusters/data-service/import-data-documents.html#import-sample-data)
## Similar Quickstart Repositories
This quickstart examples demonstrates creating REST API using NodeJS, however, quickstart is also available in following flavors and variants of javascript:
[Node.js REST API quickstart](https://github.com/couchbase-examples/nodejs-quickstart.git)
[Next.js REST API quickstart](https://github.com/couchbase-examples/nextjs-capella-quickstart)
[Ottoman quickstart](https://github.com/couchbase-examples/ottomanjs-quickstart) (Couchbase node based ODM - learn more [Ottoman](https://ottomanjs.com/) here)
## App Setup
We will walk through the different steps required to get the application running.
### Cloning Repo
```shell
git clone https://github.com/couchbase-examples/typescript-quickstart.git
```
## Install Dependencies
Any dependencies will be installed by running the npm install command, which installs any dependencies required for the project.
```sh
# Execute this command in the project's root directory which is `typescript-quickstart`
npm install
```
### Setup Database Configuration
To know more about connecting to your Capella cluster, please follow the [instructions](https://docs.couchbase.com/cloud/get-started/connect.html).
Specifically, you need to do the following:
- Create the [database credentials](https://docs.couchbase.com/cloud/clusters/manage-database-users.html) to access the travel-sample bucket (Read and Write) used in the application.
- [Allow access](https://docs.couchbase.com/cloud/clusters/allow-ip-address.html) to the Cluster from the IP on which the application is running.
All configuration for communication with the database is read from the environment variables. We have provided a convenience feature in this quickstart to read the environment variables from a local file, `config/dev.env.example`.
Create a copy of `dev.env.example` file and rename it to `dev.env` and add the values for the Couchbase connection.
```sh
DB_CONN_STR=
DB_USERNAME=
DB_PASSWORD=
```
> Note: The connection string expects the `couchbases://` or `couchbase://` part.
## Running The Application
### Directly on machine
At this point, we have installed the dependencies, loaded the travel-sample data and configured the application with the credentials. The application is now ready and you can run it.
The application will run on port specified by the `APP_PORT` variable of your configuration on your local machine (eg:, http://localhost:3000 if `APP_PORT` is set to `3000` which is the default value). You will find the Swagger documentation of the API.
```sh
# Execute this command in the project's root directory
npm start
```
### Using Docker
- Build the Docker image
```sh
# Execute this command in the project's root directory
docker build -t couchbase-typescript-express-js-quickstart .
```
- Run the Docker image
```sh
# Execute this command in the project's root directory. Replace APP_PORT with the value of your APP_PORT variable.
docker run -it --env-file config/dev.env -p ${APP_PORT}:${APP_PORT} couchbase-typescript-express-js-quickstart
# For eg: docker run -it --env-file config/dev.env -p 3000:3000 couchbase-typescript-express-js-quickstart
```
> Note: The `dev.env.example` file in the `config` folder has the connection information to connect to your Capella cluster. Create a copy of `config/dev.env.example` file and rename it to `config/dev.env` and add the values for the Couchbase connection.
### Verifying the Application
Once the application starts, you can see the details of the application on the terminal.
The application will run on the port specified by the `APP_PORT` variable in your configuration environment variable file on your local machine (eg: http://localhost:3000). You will find the interactive Swagger documentation of the API if you go to the URL in your browser. Swagger documentation is used in this demo to showcase the different API end points and how they can be invoked. More details on the Swagger documentation can be found in the [appendix](#swagger-documentation).
## Running The Tests
Create a copy of `config/test.env.example` file and rename it to `config/test.env` and add the values for the Couchbase connection.
To run the integration tests, use the following commands:
```sh
# Execute this command in the project's root directory
npm test
```
## Appendix
### Data Model
For this quickstart, we use three collections, `airport`, `airline` and `routes` that contain sample airports, airlines and airline routes respectively. The routes collection connects the airports and airlines as seen in the figure below. We use these connections in the quickstart to generate airports that are directly connected and airlines connecting to a destination airport. Note that these are just examples to highlight how you can use SQL++ queries to join the collections.
### Extending API by Adding New Entity
If you would like to add another entity to the APIs, these are the steps to follow:
- **Create the New Entity in Couchbase Bucket:**
- Utilize the [Couchbase Server interface](https://docs.couchbase.com/cloud/n1ql/n1ql-language-reference/createcollection.html) to establish the new collection within the Couchbase bucket. Alternatively the collection can be created using the [createCollection](https://docs.couchbase.com/sdk-api/couchbase-node-client/classes/CollectionManager.html#createCollection) via the SDK.
- **Define the New Route:**
- Navigate to the `src/routes` folder and create the new route.
- **Controller Configuration:**
- Develop a new file in the `controllers` folder, mirroring the existing structures (e.g., `airportController.js`). Craft the corresponding method within this file to manage the new entity.
- **Add Tests:**
- Add the tests for the new routes in a new file in the `__test__` folder similar to other collection tests.
Following these steps ensures a systematic and organized approach to expanding the API functionality with a new entity.
### Running Self Managed Couchbase Cluster
If you are running this quickstart with a self managed Couchbase cluster, you need to [load](https://docs.couchbase.com/server/current/manage/manage-settings/install-sample-buckets.html) the travel-sample data bucket in your cluster and generate the credentials for the bucket by [creating a user](https://docs.couchbase.com/server/current/manage/manage-security/manage-users-and-roles.html#add-a-user).
You need to update the connection string and the credentials in the `dev.env` file in the `config` folder.
> Note: Couchbase Server must be installed and running prior to running this app.
### Swagger Documentation
Swagger documentation provides a clear view of the API including endpoints, HTTP methods, request parameters, and response objects.
Click on an individual endpoint to expand it and see detailed information. This includes the endpoint's description, possible response status codes, and the request parameters it accepts.
#### Trying Out the API
You can try out an API by clicking on the "Try it out" button next to the endpoints.
- Parameters: If an endpoint requires parameters, Swagger UI provides input boxes for you to fill in. This could include path parameters, query strings, headers, or the body of a POST/PUT request.
- Execution: Once you've inputted all the necessary parameters, you can click the "Execute" button to make a live API call. Swagger UI will send the request to the API and display the response directly in the documentation. This includes the response code, response headers, and response body.
#### Models
Swagger documents the structure of request and response bodies using models. These models define the expected data structure using JSON schema and are extremely helpful in understanding what data to send and expect.