Getting Started

Ember Link makes adding real-time collaboration to your app effortless. This guide will help you set up Ember Link and start using its core features.

Installation

You can install Ember Link via npm or yarn or any other package manager you use:

npm install @ember-link/react
# or
yarn add @ember-link/react

Running the Ember Link Server

The easiest way to get started is by running the latest Ember Link Docker image locally.

1. Download the Docker image:

   docker pull emberlinkio/ember-link:latest

2. Run the Docker container: This will run the server on port 9000 and expose it for your application to connect. The ALLOW_UNAUTHORIZED flag is enabled for easier testing.

   docker run -d -p 9000:9000 --env PORT=9000 --env HOST=0.0.0.0 --env ALLOW_UNAUTHORIZED=true emberlinkio/ember-link:latest

Server Configuration

View all server configuration environment variables here

Connecting to Ember Link

After installing, wrap your root component with an EmberLinkProvider

import { createClient } from '@ember-link/core';

const client = createClient({
	baseUrl: 'http://localhost:9000'
});

import { createClient } from '@ember-link/core';

const client = createClient({
	baseUrl: 'http://localhost:9000'
});

import { ChannelProvider, EmberLinkProvider } from '@ember-link/react';

function App() {
	return <EmberLinkProvider baseUrl="http://localhost:9000">{children}</EmberLinkProvider>;
}

<script lang="ts">
	import { EmberLinkProvider } from '@ember-link/svelte';

	let { children } = $props();
</script>

<EmberLinkProvider baseUrl="http://localhost:9000">
	{@render children()}
</EmberLinkProvider>

Then where you plan on using Ember Link you can wrap that component with a ChannelProvider to connect to a Channel

// Returns the channel and a function that should be called
// once a user leaves the channel
const { channel, leave } = client.joinChannel('test');

// Returns the channel and a function that should be called
// once a user leaves the channel
const { channel, leave } = client.joinChannel('test');

function Channel() {
	return (
		<ChannelProvider channelName="test" options={{}}>
			<Page />
		</ChannelProvider>
	);
}

<script lang="ts">
	import { ClientProvider } from '@ember-link/svelte';

	let { children } = $props();
</script>

<ChannelProvider channelName="test">
	<Page />
</ChannelProvider>

Listening to User Presence

Track when users join or leave the collaboration session and update your own presence:

import { useMyPresence, useOthers } from '@ember-link/react';
import { useEffect } from 'react';

export const Page = () => {
	const others = useOthers();
	const [myPresence, setMyPresence] = useMyPresence();

	useEffect(() => {
		setMyPresence({ status: 'online' });
	}, [setMyPresence]);

	return (
		<div>
			{myPresence}
			{others.map((other) => {
				return <div>{other.clientId}</div>;
			})}
		</div>
	);
};

Listening to Websocket status

import { useChannel } from '@ember-link/react';
import { useEffect } from 'react';

export const Page = () => {
	const channel = useChannel();

	useEffect(() => {
		const unsub = channel.events.subscribe('status', (status) => {
			console.log('Current websocket status: ', status);
		});

		return () => {
			unsub();
		};
	}, [channel]);

	return (
		/*
			Display the status as a badge
		*/
	);
};

Next Steps

• Check out the full API documentation for each package
• Check out examples on the github repo
• Join the Ember Link community on Discord for support & updates