Get Started with Weavy in Your Angular App

A step-by-step guide to integrate Weavy components into your Angular application.

Step 1: Weavy API Key

We need the backend URL and an API key to communicate with Weavy.

First, sign up for an account

Before you can work with Weavy, you'll need to sign up for a free account or sign into your existing account.

Then, select your environment and API key to proceed with the tutorial. The API key will be automatically applied to all code snippets below.

Step 2: Install UIKit Web

Run this in your terminal:

npm install @weavy/uikit-web

Step 3: Create Weavy Service

Configuring the Weavy backend URL and issuing of access tokens is best done as a service in Angular.

Copy and paste this into a terminal window and run it:

ng generate service weavy

This generates the following files:

src/app/weavy.service.spec.ts
src/app/weavy.service.ts

Step 4: Create a Demo User

For this tutorial, we're creating a demo user. We need a display name (what the end user sees) and a unique identifier.

This is what shown for the end user in title bars, search results for users, etc.

A unique identifier for the user - cannot contain whitespace and must contain at least one non-digit.

Now create the user in Weavy through the API using curl:

curl WY_BACKEND_URL/api/users -H "Authorization: Bearer WY_API_*****************" --json "{ 'uid': 'USER_ID', 'name': 'USER_NAME' }"

Notes:

Replace WY_BACKEND_URL with the URL to your Weavy backend
Replace WY_API_***************** with an API key for your Weavy backend
Replace USER_ID with the id of the Weavy user
Replace USER_NAME with the name of the Weavy user

You can find this information in your Weavy account.

Note: Creating a user through curl is purely for demo purposes. Users created in Weavy should be done from your backend using the user API endpoints.

Step 5: Issue Access Token

For our chat component to know who we're rendering for, we must issue an access token that we'll pass on to the UIKit.

Copy and paste this into a terminal window and run it:

curl -X POST WY_BACKEND_URL/api/users/USER_ID/tokens -H "Authorization: Bearer WY_API_*****************"

This will return an access token - copy and use it below.

Notes:

Replace WY_BACKEND_URL with the URL to your Weavy backend
Replace WY_API_***************** with an API key for your Weavy backend
Replace USER_ID with the id of the Weavy user

Note: Issuing an access token using curl is for demo purposes only. Access tokens should be created from your backend; read more about authentication and access tokens.

Step 6: Edit weavy.service.ts

Open the generated weavy.service.ts file in your editor and add the following code.

import { Injectable, OnDestroy } from "@angular/core";
import { Weavy } from "@weavy/uikit-web";

@Injectable({
  providedIn: "root",
})
export class WeavyService implements OnDestroy {
  weavy = new Weavy();

  constructor() {
    this.weavy.url = new URL("WY_BACKEND_URL");
    this.weavy.tokenFactory = async (refresh) => "USER_ACCESS_TOKEN";
  }

  ngOnDestroy(): void {
    this.weavy.destroy();
  }
}

Notes:

Replace WY_BACKEND_URL with the URL to your Weavy backend
Replace USER_ACCESS_TOKEN with your issued access token

You can find this information in your Weavy account.

First we import the @weavy/uikit-web package and create a new Weavy() instance (importing the Weavy package also registers the web components for usage). Then we configure it with the URL to your Weavy backend.

To handle destruction of Weavy properly, you need to implement the OnDestroy interface in Angular.

Step 7: Create Components

Next, you need to create components for the Weavy features you want to use. In this example we'll create a component for the chat feature.

Copy and paste this into a terminal window and run it:

ng generate component chat

This generates the following files:

src/app/chat/chat.component.css
src/app/chat/chat.component.html
src/app/chat/chat.component.spec.ts
src/app/chat/chat.component.ts

Step 8: Edit chat.component.ts

Edit the generated chat.component.ts file and add the following code.

import { CUSTOM_ELEMENTS_SCHEMA, Component, Input } from "@angular/core";
import { WeavyService } from "../weavy.service";

@Component({
  selector: "app-chat",
  standalone: true,
  imports: [],
  templateUrl: "./chat.component.html",
  styleUrl: "./chat.component.css",
  providers: [WeavyService],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class ChatComponent {
  @Input() uid!: string;

  constructor(private weavyService: WeavyService) {
    this.weavyService = weavyService;
  }
}

You need to add the uid property to the component with the @Input() decorator so that you can use the component dynamically.

To make external custom web components valid in the Angular HTML, you need to add the CUSTOM_ELEMENTS_SCHEMA. As of Angular v15.2-v18 you need to make the component standalone by adding standalone: true.

You also need to connect the Weavy service to the component. This is done by importing our WeavyService, define it as a provider and adding a reference to it in the constructor.

Step 9: Edit chat.component.html

Next, you'll add the HTML for the chat building block in chat.component.html. Note the property binding for the uid property to the web component.

<wy-chat [uid]="uid"></wy-chat>

Step 10: Use Component

To use the chat component you first need to import the ChatComponent and reference it in the imports in the app component src/app/app.component.ts.

import { Component } from "@angular/core";
import { RouterOutlet } from "@angular/router";
import { ChatComponent } from "./chat/chat.component";

@Component({
  selector: "app-root",
  standalone: true,
  templateUrl: "./app.component.html",
  styleUrl: "./app.component.css",
  imports: [RouterOutlet, ChatComponent],
})
export class AppComponent {
  title = "weavy-example-app";
}

Step 11: Edit app.component.html

Then you can simply reference it in your src/app/app.component.html template using the defined component selector name.

<app-chat uid="my-chat"></app-chat>

Step 12: Run the Example

To test the example you can use the built-in Angular dev server, which will compile and start a test server. It also recompiles and reloads the app in the browser whenever you make changes.

Try it out by running ng serve in your terminal and open the app in your browser, usually on http://localhost:4200.

ng serve

Done!

Voilà! Now you have a chat component to integrate anywhere in your Angular app. Start building amazing collaboration features today!