MongoDB Stitch Server SDK
The official MongoDB Stitch Server SDK for JavaScript/TypeScript.
Index
Documentation
Discussion
Installation
NPM
Run the following in the root directory of your NPM project.
npm install mongodb-stitch-server-sdk
This will start you off with the core SDK functionality as well as the remote MongoDB service.
See Customized Dependencies (Advanced) below for customizing dependencies.
Getting Started
Creating a new app with the SDK (NPM)
Set up an application on Stitch
First, you need to create the server-side Stitch app, and (for the purpose of this quick start) enable anonymous authentication:
- Go to https://stitch.mongodb.com/ and log in to MongoDB Atlas.
- Create a new app in your project with your desired name.
- Go to your app in Stitch via Atlas by clicking Stitch Apps in the left side pane and clicking your app.
- Copy your app's client app id by going to Clients on the left side pane and clicking copy on the App ID section.
- Go to Providers from Users in the left side pane and edit and enable "Allow users to log in anonymously".
For detailed instructions, see Create a Stitch App.
Set up an NPM project
Next, you create the source for your client app.
- Ensure that you have
npm
installed. See npmjs.com. - Initialize a new NPM project:
mkdir StitchProject && cd StitchProjectnpm init
- Add the MongoDB Stitch Server SDK:
npm install mongodb-stitch-server-sdk
- Create directories for your source files:
mkdir src
- Create the file
src/index.js
and add the following code, replacing<your-client-app-id>
with the id you retrieved when setting up the application in MongoDB Stitch:
const Stitch AnonymousCredential} = ; const client = Stitch;clientauth
- Run the app by running
node src/index.js
.
Using the SDK
Initialize the SDK
When your app has started, use Stitch.initializeDefaultAppClient to initialize the Stitch SDK. Replace <your-client-app-id>
with your Stitch application's client app ID:
const Stitch AnonymousCredential = ; Stitch;
Your client app ID can be found in the Stitch UI.
Logging In
We enabled anonymous authentication in the steps above, so let's log in with it! Add the following anywhere in your code:
const client = StitchdefaultAppClient; console;clientauth;
When running this code, you should see the following in your standard out:
logging in anonymously
logged in anonymously as user 58c5d6ebb9ede022a3d75050
See StitchAuth for more information.
Executing a Stitch Function
One of Stitch's powerful features is serverless Functions. Once logged in, the Stitch client can execute remote Stitch Functions using the StitchAppClient.callFunction method:
client
Assuming you've configured your Stitch application to have a Function named "echoArg" that returns its argument, you should see a message like:
Echoed result: Hello world!
The echoArg
Function in Stitch would look something like:
// echoArg Function in the Stitch UI { return arg: arg;};
Using BSON and Extended JSON
As a convenience, the SDK includes the bson library. You can import it as you would import other classes and values from the SDK.
Here is an example of importing BSON to generate a BSON ObjectID
:
const BSON = ; let myObjectId = ;console;
Advanced Topics
Customized Dependencies
For customized dependencies, use the following:
npm install mongodb-stitch-server-corenpm install mongodb-stitch-server-services-awsnpm install mongodb-stitch-server-services-httpnpm install mongodb-stitch-server-services-mongodb-remotenpm install mongodb-stitch-server-services-twilio
Getting a StitchAppClient without Stitch.getDefaultAppClient (Advanced)
In the case that you don't want a single default initialized StitchAppClient
, you can use the following with as many client app IDs as you'd like to initialize clients for multiple app IDs:
const client = Stitch;
You can use the client returned there or anywhere else in your app by using the following:
const client = Stitch;
Changing the default data directory
Clients will generally store their data in $HOME/.stitch/<your-client-app-id>
. To modify this directory, you must initialize an app client with a custom data directory set:
const Stitch StitchAppClientConfiguration = ; const client = Stitch;
You can use the client returned there or anywhere else in your app by using the following:
const client = Stitch;
Closing the StitchAppClient
The client maintains some background processes in the event loop that must be shutdown when the client is no longer needed. Simply call close
on the client when you are done with the client:
client;