@xano/js-sdk v2.0.1

Xano JavaScript SDK

The Xano JavaScript SDK is built in pure TypeScript. Under the hood the SDK uses Axios which is not only supported by all modern browsers but allows us to be compatible with NodeJS as well.

Questions, comments or suggestions? Let us know in the Xano Community

What is Xano?

Xano is the fastest way to build a powerful, scalable backend for your app without code.

Xano gives you a scalable server, a flexible database, and a NO CODE API builder that can transform, filter, and integrate with data from anywhere. We want to enable you to validate AND grow your ideas quickly without limits or any of the barriers you might have encountered using other tools. :muscle:

Xano Links

• :globe_with_meridians: Xano Homepage

• :rocket: Xano Documentation

• :book: Xano Blog

• :house_with_garden: Xano Community

Installation

Include our script tag directly from jsDelivr:

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@xano/js-sdk@latest/dist/xano.min.js"></script>

OR use npm to install the Xano JS SDK module:

npm  install  @xano/js-sdk

OR use our pre-bundled JS bundle:

<script  type="text/javascript"  src="dist/xano.min.js"></script>

NodeJS

NodeJS users should use our XanoNodeClient instead of XanoClient. The documentation is the same, it just takes care of some inconsistencies from the web behind the scenes.

Since NodeJS isn't a browser, the storage configuration is defaulted to XanoObjectStorage.

Examples

Pre-baked Examples

Examples for all methods and simple use-cases can be found in the /examples folder.

Uploading a file

Uploading a file can be a pretty complex process but we tried our best to make it as easy as possible - simply include the file as a parameter just like you would any other:

const  file = document.getElementById("file").files[0];

xano.post("/file_upload", {
	file:  file,
}).then(
	(response) => {
		// Success!
	},
	(error) => {
		// Failure
	}
);

NodeJS users should refer to our XanoFile class.

Connecting to Realtime

Connecting to realtime is as simple as supplying a channel name and listening for events. The client will automatically authenticate if the authToken setting is set.

import { XanoClient, XanoSessionStorage } from  "@xano/js-sdk";

const  xano = new  XanoClient({
	instanceBaseUrl:  "https://x8ki-letl-twmt.n7.xano.io/",
	realtimeConnectionHash: "1lK90n16tnnylJpJ0Xa7Km6_KxA",
});

const channel = xano.channel("some_channel");

// Listening to all events
channel.on(function(action) {
	console.log("Received action", action);
});

// Listening to specific events (full list in src/enums/realtime-action.ts)
channel.on("message", function(action) {
	console.log("Received message", action);
});

channel.message({ message: "Hello world!" });

Client Documentation

XanoClient

This is the primary client class of Xano. It can be instantiated with the following parameters:

Usage:

import { XanoClient } from  "@xano/js-sdk";

const  xano = new  XanoClient({
	apiGroupBaseUrl:  "https://x8ki-letl-twmt.n7.xano.io/api:jVuUQATw",
});

XanoClient.hasAuthToken

Checks to see if the authToken has been set.

Usage:

xano.setAuthToken("eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBM....");

console.log(xano.hasAuthToken()); // true

XanoClient.setAuthToken

Sets the authentication token which makes future requests authenticated.

Depending on storage when configuring XanoClient this value could persist across browser reloads.

Usage:

xano.setAuthToken("eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBM....");

XanoClient.hasRealtimeAuthToken

Checks to see if the realtimeAuthToken has been set.

Usage:

xano.setRealtimeAuthToken("eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBM....");

console.log(xano.hasRealtimeAuthToken()); // true

XanoClient.setRealtimeAuthToken

Sets the realtime authentication token which is used on new realtime connections.

Depending on storage when configuring XanoClient this value could persist across browser reloads.

Usage:

xano.setRealtimeAuthToken("eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBM....");
xano.realtimeReconnect();

XanoClient.hasDataSource

Checks to see if the dataSource has been set.

Usage:

xano.setDataSource("develop");

console.log(xano.hasDataSource()); // true

XanoClient.setDataSource

Sets the data source which makes future requests include the X-Data-Source header.

More information about data sources can be found here

Usage:

xano.setDataSource("develop");

XanoClient.get

Makes a GET HTTP request to Xano.

This function returns a Promise that resolves to XanoResponse on success and XanoRequestError on failure.

Usage:

xano.get("/users", {
	sort_by:  "name",
}).then(
	(response) => {
		// Success!
	},
	(error) => {
		// Failure
	}
);

XanoClient.post

Makes a POST HTTP request to Xano.

This function returns a Promise that resolves to XanoResponse on success and XanoRequestError on failure.

Usage:

xano.post("/users", {
	first_name:  "Justin",
	last_name:  "Albrecht",
}).then(
	(response) => {
		// Success!
	},
	(error) => {
		// Failure
	}
);

XanoClient.patch

Makes a PATCH HTTP request to Xano.

This function returns a Promise that resolves to XanoResponse on success and XanoRequestError on failure.

Usage:

xano.patch("/users", {
	first_name:  "Justin",
}).then(
	(response) => {
		// Success!
	},
	(error) => {
		// Failure
	}
);

XanoClient.put

Makes a PUT HTTP request to Xano.

This function returns a Promise that resolves to XanoResponse on success and XanoRequestError on failure.

Usage:

xano.put("/users", {
	last_name:  "Albrecht",
}).then(
	(response) => {
		// Success!
	},
	(error) => {
		// Failure
	}
);

XanoClient.delete

Makes a DELETE HTTP request to Xano.

This function returns a Promise that resolves to XanoResponse on success and XanoRequestError on failure.

Usage:

xano.delete("/users/1", {
	optional:  "abc",
}).then(
	(response) => {
		// Success!
	},
	(error) => {
		// Failure
	}
);

XanoClient.head

Makes a HEAD HTTP request to Xano.

This function returns a Promise that resolves to XanoResponse on success and XanoRequestError on failure.

Usage:

xano.head("/users/1", {
	optional:  "abc",
}).then(
	(response) => {
		// Success!
	},
	(error) => {
		// Failure
	}
);

XanoResponse

The response class of a successful GET/POST/PATCH/PUT/DELETE/HEAD request.

Usage:

xano.get("/users").then((response) => {
	const  body = response.getBody();
	const  headers = response.getHeaders();
	const  statusCode = response.getStatusCode();
});

XanoRequestError

The response class of a failed GET/POST/PATCH/PUT/DELETE/HEAD request.

This class extends the JS Error class.

Usage:

xano.get("/users").then(
	(response) => {},
	(error) => {
		const  xanoHttpResponse = error.getResponse();
		const  body = xanoHttpResponse.getBody();
		const  headers = xanoHttpResponse.getHeaders();
		const  statusCode = xanoHttpResponse.getStatusCode();
	}
);

XanoFile

XanoFile is a class for NodeJS only!

The XanoFile class is required to upload a file from the NodeJS file system.

Usage:

const  fs = require("fs/promises");
const  fileName = "512x512bb.jpg";

fs.readFile("./" + fileName).then(
	(imageBuffer) => {
		const  xImage = new  XanoFile(fileName, imageBuffer);

		xano.post("/file_upload", {
			image:  xImage,
		}).then(
			(response) => {
				// Success!
			},
			(error) => {
				// Error
			}
		);
	}
);

XanoBaseStorage

The XanoBaseStorage class is extended for storing/retrieving information like the authToken.

Xano supplies four Storage classes by default:

Each class that extends XanoBaseStorage share the following functions:

Usage:

import { XanoClient, XanoSessionStorage } from  "@xano/js-sdk";

const  xano = new  XanoClient({
	apiGroupBaseUrl:  "https://x8ki-letl-twmt.n7.xano.io/api:jVuUQATw",
	storage:  new  XanoSessionStorage(),
});

Realtime Documentation

Every Xano instance comes with a realtime socket server that can be enabled on a per-workspace basis that supports Xano to client messaging, client to public channel messaging, client to private channel messaging, and client to client (private) messaging.

XanoClient.channel

Connects the XanoClient to a realtime websocket channel.

This function returns an instance of XanoRealtimeChannel

Usage:

const channel = xano.channel("stats", {
	presence:  true,
});

XanoClient.realtimeReconnect

If you are connected to the realtime websocket server this will trigger a reconnect. This function is usefull after updating your realtimeAuthToken to trigger re-authentication.

Usage:

xano.setRealtimeAuthToken("eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBM....");
xano.realtimeReconnect();

XanoRealtimeChannel.on (all events)

The on returns an event stream that can be subscribed to with a success and error function:

Usage:

channel.on(
	(action) => {
		// Success!
	},
	(error) => {
		// Failure
	}
);

XanoRealtimeChannel.on (specific events)

The on returns an event stream that can be subscribed to with an action, success function, and error function:

Usage:

// Using the string action
channel.on("message", 
	(action) => {
		// Success!
	},
	(error) => {
		// Failure
	}
);

// Using the typescript enum:
channel.on(ERealtimeAction.Message, 
	(action) => {
		// Success!
	},
	(error) => {
		// Failure
	}
);

XanoRealtimeChannel.message

Sends a message from the client to the channel

Usage:

// Send a message to only other authenticated users in a channel
channel.message({ message: "Hello world!" }, {
	authenticated: true
});

XanoRealtimeChannel.getPresence

Sends a message from the client to the channel.

Presence is only available on channels joined with XanoRealtimeChannelOptions.presence set to true

Returns an array of XanoRealtimeClient

Usage:

const users = channel.getPresence();

XanoRealtimeChannel.history

Sends a message to realtime requesting the latest channel history. The response will be sent through the history action

History is only available on channels with message history enabled

Usage:

channel.history();

channel.on('history', function(action) {
	console.log('history', action);
});

XanoRealtimeChannel.destroy

Leaves the channel and disconnects from the realtime websocket server if its the last open channel. You will need to create a new XanoRealtimeChannel instance to rejoin or interact with the channel again.

Usage:

channel.destroy();

XanoRealtimeClient.message

Sends a private message directly to the XanoRealtimeClient client.

Usage:

const presence = channel.getPresence();

for (const client of presence) {
	client.message({ message: "Saying hello to everyone in private!" });
}

XanoRealtimeClient.history

Sends a message to realtime requesting the latest channel history. The response will be sent through the history action

History is only available on channels with message history enabled

Usage:

client.history();

channel.on('history', function(action) {
	console.log('history', action);
});

XanoRealtimeChannelOptions

Leaves the channel and disconnects from the realtime websocket server if its the last open channel. You will need to create a new XanoRealtimeChannel instance to rejoin or interact with the channel again.

XanoRealtimeClient

Presence user or initiator of a action

XanoRealtimeAction

The action payload sent and received through the XanoRealtimeChannel

XanoRealtimeActionOptions

The action options when sending and receiving actions through the XanoRealtimeChannel.message

TypeScript support

This package includes TypeScript declarations. We support projects using TypeScript versions >= 3.1.