Angular

Getting Started with Angular & Apollo

Published Oct 28, 2019

Updated Feb 14, 2023

9 min read

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

GraphQL came about to solve some of the issues present with RESTful API architecture. Issues like: over-fetching (getting far more data than I need), under-fetching (not getting enough data and having to make another round-trip), all-or-nothing (if an error occurs while trying to retrieve any of the data, the operation fails), type-safety (require what is expected, know what will be returned; thus, fewer bugs), etc. It is a very powerful spec (all hail the mighty resolver) that has caused a pretty massive shift in the industry.

The focus of this article will be on interacting with a GraphQL API to query and mutate data through an Angular SPA. We will build an app around an Event Calendar, view events, create & edit events, etc. To connect to our GraphQL API we will be using the Apollo Angular library. Apollo is a great platform implementation of GraphQL with a variety of awesome libraries, toolsets, even a GraphQL server.

Follow along with the repo here.

Setup

To begin, let’s create a new Angular Application using the angular cli. If you have not installed the angular cli, it is very simple, open your favorite terminal and install it globally with npm:

npm i -g @angular/cli

Once completed, you can validate that it was installed successfully by checking the version:

ng --version

Create the App

Now lets create the app using the cli (you will want to be in the directory where you want the app installed, if so, cd into that directory first):

$ ng new event-calendar --style=scss --routing=true

And huzzah! A new angular app! For sanity sake, let’s make sure everything went smoothly, cd into the new app directory and run it:

$ cd event-calendar
$ ng serve

If the app started successfully, you should be able to open a web browser window and navigate to http://localhost:4200/ and see the app. Note. 4200 is the default port, if you would like to run it on some other port, add the port as a param to the ng serve command:

$ ng serve --port 4201

Adding Apollo

The ng add functionality of the cli makes it incredibly easy to add new modules to our angular apps. Including the angular apollo GraphQL client implementation module;

$ ng add apollo-angular

This command does a few things for us:

Installs and adds the required dependencies to our package.json
Creates a GraphQL module: ./src/app/graphql.module.ts which has the initial setup required to create a connection to our graphql server and expose the connection as an angular module
Adds the GraphQL module to the Application module: ./src/app/app.module imports property to make it available to our application.

This is awesome as it took care of the initial boilerplate work for us. The only thing we need to do is set the URI of where our GraphQL API server is running. Open the ./src/app/graphql.module.ts GraphQL Module file and you will see a const variable named: uri that is currently and empty string with a helpful comment saying telling you to “<-- add the URL of the GraphQL server here”. Go ahead and do as the comment says and let's add our GraphQL Server URI. For the purpose of this article, the URI will be: http://127.0.0.1:3000/graphql. Note this is a local graphql api I have running, checkout the repo for more information.

Adding Angular Material Styling

The focus of this article is not on Angular Material, but it is a component of this project. Checkout the Angular Material Docs for usage, component docs, guides, etc. We will add the angular material module to our app using ng add just like we did with apollo:

$ ng add @angular/material

This will prompt you with some questions:

Choose a prebuilt theme name, or “custom” for a custom theme → I went with Deep Purple/Amber. Choose whatever you would like.
Set up HammerJS for gesture recognition → Y
Set up browser animations for Angular Material → Y

And just like with apollo, this will install the required dependencies and update the package.json. It also add the theming info to ./src/styles.scss as well as importing the Roboto & Material Design icon fonts.

Getting Calendar Events

That is enough boilerplate/setup. Time to start leveraging the power of GraphQL. Let’s start with a query to get a list of events for our calendar and display these events.

Creating the calendar-event module

Angular architecture promotes the creation of modules; think package-by-feature. A module should contain all of the necessary components to provide for the full feature. Things like:

Routing
Models
Services
Route Guards
Components

Those are all traditional angular class types, we will also have:

Queries
Mutations

To support this module interacting with our GraphQL server to query & mutate data. Again, we will use the cli to create our module:

$ ng g module calendar-event --routing=true

This creates a directory called ./src/app/calendar-event for us with 2 files: ./src/app/calendar-event/calendar-event-routing.module.ts and ./src/app/calendar-event/calendar-event.module.ts. These are the building blocks of our module. We can leave these alone for now.

Calendar Event Models

Let’s create a model that will represent a calendar event. Create a directory called models inside of ./src/app/calendar-event. And in this directory create a file: calendar-event.model.ts. This is where we will define the models that represent a calendar event entry.

export type EventStatus = ‘UPCOMING’ | ‘STARTED’ | ‘COMPLETED’;
export type AttendingStatus = ‘GOING’ | ‘PENDING’ | ‘NOT_GOING’;

export type Guest = {
	_id: string;
	name: string;
	email: string;
	attending: AttendingStatus;
}

export type CalendarEvent = {
	_id: string;
	Status: EventStatus;
	eventStart: string;
	startTime: string;
	eventEnd: string;
	endTime: string;
	name: string;
	description?: string;
	location?: string;
	guests?: Guest[];
}

GraphQL Queries

To solve the over/under-fetching problem with REST, GraphQL exists as a querying framework for your API. What this means is, as the client/consumer of the API, you can define what fields you want returned from the API. This is incredibly powerful. It allows us to select only the fields we want/need to be returned without the potential overhead of all the fields.

On the flipside, there is not a potential second round trip request. For instance, if you have a list of objects and in your list you only need the id and a couple fields, then that is your query and that is what the API returns; no extra bloat from fields you do not need. Then if the user navigates to a details page, you can run another query to return all of the fields in the object and display those. We can also specify multiple queries in one request and it will return the results from all queries.

Note it does not process the queries necessarily in the order you give them.

Let’s look at a quick example of this.

For this example, we have an API that has two queries it exposes: hello which returns a string: ‘HELLO’, and world which also returns a string: ‘WORLD’. To retrieve both, we can write a query:

query RetrieveHelloWorld {
	hello
	world
}

And when submitted, it will run both queries and return both in the response:

{
	“data”: {
		“hello”: “HELLO”,
		“world”: “WORLD”
	}
}

Awesome! Both queries and data returned. This is amazing. Think on load of an application, you could get the authenticated user and any initial data you would like instead of having to make each request separately making multiple roundtrips to the server.

Adding Queries in Apollo Angular

Apollo provides a couple ways we can query for data in Angular. Let’s explore them now.

The first way to run a query is by utilizing the Apollo service provided by the apollo-angular library. Just like any service provider, inject the Apollo service in the constructor of your component and pass the graphql query in to the .watchQuery method on the Apollo service. The valueChanges of this method return an Observable of our data that we can interact with. Let’s create a component to query for a list of CalendarEvent records:

//src/app/calendar-event/containers/calendar-events-list-container/calendar-events-list-container.component.ts
import { Component, OnInit } from '@angular/core';
import { Apollo } from 'apollo-angular';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';
import gql from 'graphql-tag';

import { CalendarEvent } from '../../models;

const calendarEventsListQuery = gql`
	query CalendarEventsQuery {
		events {
			_id
			name
			description
			eventStart
			startTime
			eventEnd
			endTime
		}
	}
`;

@Component({
	selector: ‘app-calendar-events-list-container’,
	templateUrl: ‘./calendar-events-list-container.component.html’,
	styleUrls: [‘./calendar-events-list-container.component.scss’]
})
export class CalendarEventsListContainerComponent implements OnInit {
	calendarEvents$: Observable<CalendarEvent[]>;

	constructor(private readonly apollo: Apollo) {}

	ngOnInit() {
		// use injected apollo service to run query
		// response JSON returns as { data: { events: [] } }
		// to get the calendarEvents$, map to the data.events
		this.calendarEvents$ = this.apollo.
			.watchQuery({ query: calendarEventsListQuery })
			.valueChanges.pipe(map(({ data }) => data.events));
	}
}

Super simple. The valueChanges getter on the Apollo service returns an observable of our data. We can use this with the map operator to select the events from the returned JSON data. We can also pass variables into our queries by passing an object to the variables prop in the .watchQuery method. If we want to pass in a variable like first to get the first # of results that match the query, update the query to include the variable:

const calendarEventsListQuery = gql`
  query CalendarEventsQuery($first: Int!) {
    events(first: $first) {
      _id
      name
      description
      eventStart
      startTime
      eventEnd
      endTime
    }
  }
`;

And then update the call to the Apollo service:

const variables = { first: 10 }
this.calendarEvents$ = this.apollo.
  .watchQuery({ query: calendarEventsListQuery, variables })
	.valueChanges.pipe(map(({ data }) => data.events));

Check out the Query Apollo Angular docs here for more info.

The other, and my preferred, way to query for data is to create a custom service provider class that extends Query and defines our query. Query is a type exposed by the apollo-angular library and accepts two generic types: the response type, and a type representing any variables to pass to the query. Let’s move our Calendar Events list query from above and build out a query service for it instead:

import { Injectable } from '@angular/core';
import { Query } from 'apollo-angular';
import gql from 'graphql-tag';

import { CalendarEvent } from '../../models;

type CalendarEventsListResponse = {
	events: CalendarEvent[];
}

@Injectable()
export class CalendarEventsQuery extends Query<CalendarEventsListResponse> {
	document = gql`
		query CalendarEventsQuery {
			events {
				_id
				name
				description
				eventStart
				startTime
				eventEnd
				endTime
			}
		}
	`;
}

Because this is a service provider, and is annotated Injectable(), we need to provide it to our module to make it available for dependency injection. To achieve this, add it to the providers prop on the NgModule

// imports
import { CalendarEventsQuery } from ‘./graphql’;

@NgModule({
	// declarations, imports, etc
	providers: [
		// other services
		CalendarEventsQuery
	]
})
export class CalendarEventModule {}

And we can now update our container component:

//src/app/calendar-event/containers/calendar-events-list-container/calendar-events-list-container.component.ts
import { Component, OnInit } from '@angular/core';
import { Apollo } from 'apollo-angular';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';
import gql from 'graphql-tag';

import { CalendarEventsQuery } from '../../graphql;

@Component({
	selector: ‘app-calendar-events-list-container’,
	templateUrl: ‘./calendar-events-list-container.component.html’,
	styleUrls: [‘./calendar-events-list-container.component.scss’]
})
export class CalendarEventsListContainerComponent implements OnInit {
	calendarEvents$: Observable<CalendarEvent[]>;

	constructor(private readonly calendarEventsQuery: CalendarEventsQuery) {}

	ngOnInit() {
		// use injected apollo service to run query
		// response JSON returns as { data: { events: [] } }
		// to get the calendarEvents$, map to the data.events
		this.calendarEvents$ = this.calendarEventsQuery.watch().valueChanges.pipe(map({ data }) => data.events));
	}
}

And, just like with the first option, we can add variables as well. First we need to update our CalendarEventsQuery service class:

import { Injectable } from '@angular/core';
import { Query } from 'apollo-angular';
import gql from 'graphql-tag';

import { CalendarEvent } from '../../models;

type CalendarEventsListResponse = {
	events: CalendarEvent[];
}

export type CalendarEventsListVariables = {
	first: number;
}

@Injectable()
export class CalendarEventsQuery extends Query<CalendarEventsListResponse, CalendarEventsListVariables> {
	document = gql`
		query CalendarEventsQuery($first: Int!) {
			events(first: $first) {
				_id
				name
				description
				eventStart
				startTime
				eventEnd
				endTime
			}
		}
	`;
}

And now we pass the variables into the watch method on our injected query instance in our component:

//src/app/calendar-event/containers/calendar-events-list-container/calendar-events-list-container.component.ts
import { Component, OnInit } from '@angular/core';
import { Apollo } from 'apollo-angular';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';
import gql from 'graphql-tag';

import { CalendarEventsQuery } from '../../graphql;

@Component({
	selector: ‘app-calendar-events-list-container’,
	templateUrl: ‘./calendar-events-list-container.component.html’,
	styleUrls: [‘./calendar-events-list-container.component.scss’]
})
export class CalendarEventsListContainerComponent implements OnInit {
	calendarEvents$: Observable<CalendarEvent[]>;

	constructor(private readonly calendarEventsQuery: CalendarEventsQuery) {}

	ngOnInit() {
		// use injected apollo service to run query
		// response JSON returns as { data: { events: [] } }
		// to get the calendarEvents$, map to the data.events
		this.calendarEvents$ = this.calendarEventsQuery.watch({ first: 10  }).valueChanges.pipe(map({ data }) => data.events));
	}
}

Very similar to what we had in the first option. The advantage here is that, because we separated out the query into its own service class, we can inject it into any component to connect and run our query. It makes the query reusable in case multiple components wanted to consume the data. For more information about this method of querying for data, check out the query service docs here.

Creating a Calendar Event

Queries are all about fetching data. The convention is that a Query should not change any data in a data platform. However, creating, updating and deleting data is almost always a requirement. GraphQL handles this with the concept of a Mutation. A mutation is really similar in structure to a query: you pass in the name of the mutation, any necessary variables, and the data you want returned. The key differences are that a mutation request starts with the keyword mutation and if we need to pass input to the mutation (like the object to create/update) that object needs to be an input type object.

GraphQL Mutations

Let’s go through a quick example from the docs First let’s define our input type which we will pass as a variable to our mutation:

input ReviewInput {
	stars: Int!
	commentary: String
}

The key here is that our type of ReviewInput is input. The mutation will fail if this not declared as input. This is one of the biggest complaints against GraphQL as it can lead to duplicated types. I personally find this helpful as it helps me to be very specific about the shape of my input and what I want to require to create or update a data object. And now to write our mutation:

mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
	createReview(episode: $ep, review: $review) {
		start
		commentary
	}
}

This should look very familiar. As I mentioned, the shape of the request is very similar to a Query. Key difference being the mutation keyword to start the request.

Adding Mutations in Apollo Angular

Now for the angular part. Just like queries above, we can use the Apollo service and then dispatch a mutation with the mutate({ mutation }) method. But instead, let’s use a Mutation service provider; code-reusability and all. The Mutation class we will extend is very similar to the Query class, it accepts a couple generics: the return type from the mutation, and a type that represents the variables to pass to the mutation.

import { Injectable } from ‘@angular/core’;
import { Mutation } from ‘apollo-angular’;
import gql from ‘graphql-tag’;

import { CalendarEvent } from ‘../../models’;

type CreateCalendarEventResponse = {
	createEvent: CalendarEvent;
};

type CreateCalendarEventVariables = {
	event: CalendarEvent;
};

@Injectable()
export class CreateCalendarEventMutation extends Mutation<CreateCalendarEventResponse, CreateCalendarEventVariables> {
	document = gql`
		mutation CreateCalendarEvent($event: CalendarEventInput!) {
			createEvent(event: $event) {
				_id
				status
				name
				description
				eventStart
				startTime
				eventEnd
				endTime
				location
				recurring
				guests {
					_id
					name
					email
					attending
				}
			}
		}
	`;
}

Super straightforward. Create a mutation request object where we can pass in our $event variable that will be provided through the CreateCalendarEventVariables type, give it the name of our mutation - createEvent - reference the variable, and list the fields we want returned.

Just like the query, since this is annotated as @Injectable(), we need to provide it to our module, open the calender-event.module.ts again and lets add it to our providers prop:

// imports
import { CalendarEventsQuery, CreateCalendarEventMutation } from ‘./graphql’;

@NgModule({
	// declarations, imports, etc
	providers: [
		// other services
		CalendarEventsQuery,
		CreateCalendarEventMutation
	]
})
export class CalendarEventModule {}

Create a container component that will inject the CreateCalendarEventMutation service. It exposes a mutate method where we will pass our variables: { event: CalendarEvent } and then subscribe to the result. To keep it simple, on subscribe, we will route to the CalendarEventDetails component which will display the details of the newly created CalendarEvent:

import { Component } from ‘@angular/core’;
import { Router } from ‘@angular/router’;

import { CalendarEvent } from ‘../../models’;
import { CreateCalendarEventMutation } from ‘../../graphql’;

@Component({
	selector: ‘app-create-calendar-event-container’,
	templateUrl: ‘./create-calendar-event-container.component.html’,
	styleUrls: [‘./create-calendar-event-container.component.scss’]
})
export class CreateCalendarEventContainerComponent {
	constructor(private readonly createCalendarEventMutation: CreateCalendarEventMutation, private readonly router: Router) {}

	createCalendarEvent(event: CalendarEvent) {
		this.createCalendarEventMutation.mutate({ event }).subscribe(({ created }) => {
			// created is the data.createdEvent response from the mutation
			// the type is CalendarEvent
			// route to the details page
			this.router.navigate([‘/calendar-events/details’, created._id]);
		}
	}
}

When the createCalendarEvent function is invoked with the event data, like from the user entering the data from a form, we use the injected CreateCalendarEventMutation instance to dispatch our mutation with the CalenderEvent. When it completes, we subscribe to the results which should contain the created CalendarEvent data and navigate to the event details page.

Conclusion

There is a lot more to the apollo angular library. It helps a lot with the abstraction of connecting to a GraphQL API, handling data caching, and providing convenience classes to perform our queries and mutations.

This article only covers a couple quick examples of queries and mutations. Check out the repo for more, as well as the forms to enter and save CalendarEvent records. I hope you found this article helpful, thanks for reading along.

References

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

SSR Finally a First-Class Citizen in Angular?

I am sure you've already heard about server-side rendering (SSR). Generally, it's a technique used to deliver the HTML content generated by the server to the client. The client-side JavaScript framework then hydrates that HTML content to provide a fully interactive application. SSR provides numerous benefits if used correctly, including improved initial load times, better content indexing by search engines, and improved performance on lower-tier devices. Driven by the need for faster, more efficient web applications, with the rise in popularity of Node.js and, thus, server-side JavaScript, SSR has become a de facto standard in modern web development frameworks. At first, SSR was being provided as a part of meta-frameworks like Next.js, Nuxt, or Analog.js. Then, React introduced React Server Components, which marked a significant milestone in the way we think about front-end development. We think of front-end frameworks as being effectively full-stack, and a purely SPA approach is falling out of favor. However, I'm willing to bet that if you're a developer focused mostly on Angular, you may not have heard as much about SSR as your React counterparts. For a long time, Angular has been mostly focused on the SPA approach, and while we had Angular Universal or Analog.js, it was not as widely adopted. And that makes sense, given that Angular was widely regarded as best suited for complex, interactive applications, such as SaaS products or internal company tools, where SEO and initial load times were not as critical as they are for consumer-facing applications. Nevertheless, we have been blessed with the so-called Angular Renaissance, which has, among other things, brought SSR to the forefront of Angular development with the @angular/ssr package. Let's look at what Angular SSR is, how it works, and how you can get started. @angular/ssr The @angular/ssr package is not new; it was written from scratch. It's still Angular Universal. However, it's been pulled into the Angular CLI repository, and the appropriate schematics have been added to make it easier to use. What that means is that you can now add SSR to your Angular application with a single command: ` and you can generate a new SSR application with: ` And to make SSR a first-class citizen, the Angular team is planning to make it the default in the next version. But surely, it's not only rebranding and some CLI commands, you may say. And you're right. You may remember that hydration in Angular Universal has not been optimal as it was destructive and required essentially a complete re-render of the application, thus pretty much negating the benefits of SSR. With the introduction of non-destructive hydration in Angular 16 and its stability in Angular 17, the Angular team has taken a significant step forward in making SSR a first-class citizen. How to Make an SSR-capable Angular Application Let's look at how to use Angular SSR in practice by creating a simple SSR app. First, we need to create a new Angular application with SSR support: ` That will generate a few server-specific files: - server.ts, which is an Express server configured to handle Angular SSR requests by default but can also be extended to handle API routes, or anything else that Express can handle. - src/app/app.config.server.ts provides configuration for the server application similar to your app.config.ts, which defines the configuration for your client application. Both export an instance of ApplicationConfig - src/main.server.ts bootstraps the server application in a similar way to what main.ts does for your client app by calling the bootstrapApplication function. You should have an SSR application ready just like that. You can verify that by running ng serve. The terminal output should show you information about the server bundles generated, and you should be able to see the default app when going to http://localhost:4200. Open the Developer Tools and check the console to see that hydration is enabled. You'll see a message with hydration-related stats, such as the number of components and nodes hydrated. Speaking of hydration... Client Hydration If you open the src/app/app.config.ts in your new SSR application, you'll notice one interesting provider: provideClientHydration(). This provider is crucial for enabling hydration - a process that restores the server-side rendered application on the client. Hydration improves application performance by avoiding extra work to re-create DOM nodes. Angular tries to match existing DOM elements to the application's structure at runtime and reuses DOM nodes when possible. This results in a performance improvement measured using Core Web Vitals statistics, such as reducing the Interaction To Next Paint (INP), Largest Contentful Paint (LCP), and Cumulative Layout Shift (CLS). Improving these metrics also positively impacts SEO performance. Without hydration enabled, server-side rendered Angular applications will destroy and re-render the application's DOM, which may result in visible UI flicker, negatively impact Core Web Vitals like LCP, and cause layout shifts. Enabling hydration allows the existing DOM to be reused and prevents flickering. Event Replay and Improved Debugging With Angular 18, event replay, a feature that significantly enhances the SSR experience, came into developer preview. Event replay captures user interactions during the SSR phase and replays them once the application is hydrated. This ensures that user actions, such as adding items to a cart, are not lost during the hydration process, providing a seamless user experience even on slow networks. To enable event replay, you can add withEventReplay to your provideClientHydration call: ` Furthermore, Angular 18 takes another step towards making SSR a first-class citizen by enhancing the debugging experience with Angular DevTools. Now, DevTools include overlays and detailed error breakdowns, empowering developers to visualize and troubleshoot hydration issues directly in the browser. Constraints However, hydration imposes a few constraints on your application that are not present without hydration enabled. Your application must have the same generated DOM structure on both the server and the client. The hydration process expects the DOM tree to have the same structure in both environments, including whitespaces and comment nodes produced during server-side rendering. Direct DOM Manipulation The fact that server and client DOM structures must match means that components that manipulate the DOM using native DOM APIs or use innerHTML or outerHTML will encounter hydration errors. The errors are thrown because Angular is unaware of these changes and cannot resolve them during hydration. Examples include accessing the document, querying for specific elements, and injecting additional nodes using appendChild. Detaching DOM nodes and moving them to other locations will also cause errors. Direct DOM manipulation is generally considered bad practice in Angular, so I recommend refactoring your components to avoid it regardless of hydration. However, in warranted cases where refactoring is not feasible, you can use the ngSkipHydration attribute until a hydration-friendly solution can be implemented. You can use it directly in a template: ` or as a host binding: ` > Note: The ngSkipHydration attribute forces Angular to skip hydrating the entire component and its children. So use this attribute carefully, as, for example, applying it to your root application component would effectively disable hydration for the entire application. Valid HTML Structure Another constraint is that invalid HTML structures in component templates can result in DOM mismatch errors during hydration. Common issues include: - without a - inside a - inside an - inside another Again, if you have an invalid HTML, you should fix this regardless of hydration. If you are unsure about your HTML's validity, you can use the W3 validator to check it. Zoneless apps or custom Zone.js Hydration relies on a signal from Zone.js when it becomes stable. Custom or "noop" Zone.js implementations may thus disrupt the timing of this event, triggering the serialization or cleanup process too early or too late. This configuration is not yet fully supported. While Zoneless is already available in developer preview and we could assume this issue will be resolved when it lands as stable, there is no explicit ETA mentioned in the official roadmap. I18n One of the biggest blockers for adoption of client hydration was the lack of support for internationalization with hydration. By default, Angular 17 skipped hydration for components that used i18n blocks, re-rendering them from scratch. In Angular 18, however, hydration for i18n blocks got into developer preview. To enable hydration for i18n blocks, you can add withI18nSupport to your provideClientHydration call. ` Third-Party Libraries with DOM Manipulation The last thing to consider is third-party libraries that manipulate DOM, such as D3 charts. They could cause DOM mismatch errors when hydration is enabled. You can use the ngSkipHydration attribute to skip hydration for components rendered using these libraries. Conclusion The Angular team has been doing great work to make the framework more modern and competitive, hearing the community feedback and adjusting the roadmap accordingly. And SSR is an excellent example of that. With the introduction of non-destructive hydration in Angular 16 and making it stable in Angular 17, the Angular team has taken a significant step forward in making SSR a first-class citizen in Angular. The @angular/ssr package is now part of the Angular CLI, making adding SSR to your Angular application easier. The Angular team plans to make SSR the default in the next version, further solidifying its position in the Angular ecosystem. However, as with any new feature, there are some constraints and best practices to follow when using SSR with Angular. You should be aware of hydration's limitations and ensure your application is compatible with it. However, if you follow the guidelines provided by the Angular team, you should be able to take advantage of the benefits of SSR without any significant issues....

Jun 26, 2024

8 mins

AngularJavaScriptExpress.js

Using HttpClient in Modern Angular Applications

Introduction With all the wonderful treats that the Angular team has given us during the recent "renaissance" era, many new developers are joining in on the fun. And one of the challenges they'll face at some point is how to call an API from your Angular application properly. Unfortunately, while searching for a guide on how to do this, they might stumble upon a lot of outdated information. Hence, this article should serve as a reliable guide on how to use the HttpClient in Angular >= 17. The Setup To make an HTTP request in Angular, you can take advantage of the HttpClient provided by the @angular/common/http package. To use it, you'll need to provide it. Here's how you can do that for the whole application using the bootstrapApplication function from @angular/platform-browser: ` With that, you should be good to go. You can now inject the HttpClient into any service or component in your application. Using HttpClient in Services Let's take a common example: You have a database object, say a Movie, and you want to implement CRUD operations on it. Typically, you'll want to create a service that provides methods for these operations. Let's call this service MovieService and create a skeleton for it with a method for getting all movies. ` Implementing the Method using HttpClient Let's assume we have a GraphQL API for our movies. We can implement our getAllMovies using HttpClient to make a request to fetch all movies. First, we will need to define a new type to represent the response from the API. This is especially important when you are using GraphQL, which may return a specific structure, such as: ` When working with a real API, you'll likely use some code generator to generate the types for the response from the GraphQL schema. But for the sake of this example, we'll create an interface to represent the response manually: ` Now, we can implement the getAllMovies method using HttpClient: ` > Note: The post method is used here because we are sending a request body. If you are making a GET request (e.g. to a REST API), you can use the get method instead. The getAllMovies method returns an Observable of MoviesListResponse. In this example, I have typed it explicitly to make it obvious at first glance, but you could also omit the type annotation, and TypeScript should infer it. > Note: While I'm excited about signals as much as the next guy, making HTTP requests is one of the typical async operations for which RxJS Observables are a perfect fit, making a great argument for RxJS still having a solid place in Angular alongside signals. Using the Service in a Component Now that we have our MovieService set up, we can use it as a component to fetch and display all movies. But first, let's create a Movie interface to represent the structure of a movie. Trust me, this will prevent many potential headaches down the line. Although using any at the beginning and implementing the types later is a valid approach in some cases, using data fetched from an API without validating the type will inevitably lead to bugs that are difficult to solve. ` Now, we can start implementing our standalone MoviesComponent: ` In this component, we are calling the getAllMovies method from the MovieService in the constructor to fetch all movies and assign them to the movies property which we will use to display the movies in the template. ` In this case, placing our code inside the constructor is safe because it doesn’t depend on any @Input(). If it were, our code would fail because the inputs aren’t initialized at time of instantiation. That's why it is sometimes recommended to place logic in ngOnInit instead. You could also put this call in an arbitrary method that is called e.g. on a button click. Another way to handle the subscription is to use the async pipe in the template. This way, Angular will automatically subscribe and unsubscribe from the observable for you and you won't have to assign the response to a property in the component. Due to the structure of the returned data, however, we'll need to use the RxJS map operator to extract the movies from the response. ` > Note using the pipe method to chain the map operator to the observable returned by getAllMovies. This is a common pattern when working with RxJS observables introduced in RxJs 5.5. If you see code that uses the map operator directly on the observable and wonder why it isn't working for you, it's likely using an older version of RxJS. Now, we can simply apply the async pipe in the template to subscribe to the observable and display the movies: ` Conclusion HttpClient in Angular is pretty straightforward, but with all the changes to RxJS and Angular in the past few years, it can pose a significant challenge if you're not super-experienced with those technologies and stumble upon outdated resources. Following this article, you should hopefully be able to implement your service using HttpClient to make requests to an API in your modern Angular application and avoid the struggle of copying outdated code snippets....

Mar 27, 2024

4 mins

AngularJavaScript

Introduction to Zod for Data Validation

As web developers, we're often working with data from external sources like APIs we don't control or user inputs submitted to our backends. We can't always rely on this data to take the form we expect, and we can encounter unexpected errors when it deviates from expectations. But with the Zod library, we can define what our data ought to look like and parse the incoming data against those defined schemas. This lets us work with that data confidently, or to quickly throw an error when it isn't correct. Why use Zod? TypeScript is great for letting us define the shape of our data in our code. It helps us write more correct code the first time around by warning us if we are doing something we shouldn't. But TypeScript can't do everything for us. For example, we can define a variable as a string or a number, but we can't say "a string that starts with user_id_ and is 20 characters long" or "an integer between 1 and 5". There are limits to how much TypeScript can narrow down our data for us. Also, TypeScript is a tool for us developers. When we compile our code, our types are not available to the vanilla JavaScript. JavaScript can't validate that the data we actually use in our code matches what we thought we'd get when we wrote our TypeScript types unless you're willing to manually write code to perform those checks. This is where we can reach for a tool like Zod. With Zod, we can write data schemas. These schemas, in the simplest scenarios, look very much like TypeScript types. But we can do more with Zod than we can with TypeScript alone. Zod schemas let us create additional rules for data parsing and validation. A 20-character string that starts with user_id_? It's z.string().startsWith('user_id_').length(20). An integer between 1 and 5 inclusive? It's z.number().int().gte(1).lte(5). Zod's primitives give us many extra functions to be more specific about *exactly* what data we expect. Unlike TypeScript, Zod schemas aren't removed on compilation to JavaScript—we still have access to them! If our app receives some data, we can verify that it matches the expected shape by passing it to your Zod schema's parse function. You'll either get back your data in exactly the shape you defined in your schema, or Zod will give you an error to tell you what was wrong. Zod schemas aren't a replacement for TypeScript; rather, they are an excellent complement. Once we've defined our Zod schema, it's simple to derive a TypeScript type from it and to use that type as we normally would. But when we really need to be sure our data conforms to the schema, we can always parse the data with our schema for that extra confidence. Defining Data Schemas Zod schemas are the variables that define our expectations for the shape of our data, validate those expectations, and transform the data if necessary to match our desired shape. It's easy to start with simple schemas, and to add complexity as required. Zod provides different functions that represent data structures and related validation options, which can be combined to create larger schemas. In many cases, you'll probably be building a schema for a data object with properties of some primitive type. For example, here's a schema that would validate a JavaScript object representing an order for a pizza: ` Zod provides a number of primitives for defining schemas that line up with JavaScript primitives: string, number, bigint, boolean, date, symbol, undefined, and null. It also includes primitives void, any, unknown, and never for additional typing information. In addition to basic primitives, Zod can define object, array, and other native data structure schemas, as well as schemas for data structures not natively part of JavaScript like tuple and enum. The documentation contains considerable detail on the available data structures and how to use them. Parsing and Validating Data with Schemas With Zod schemas, you're not only telling your program what data should look like; you're also creating the tools to easily verify that the incoming data matches the schema definitions. This is where Zod really shines, as it greatly simplifies the process of validating data like user inputs or third party API responses. Let's say you're writing a website form to register new users. At a minimum, you'll need to make sure the new user's email address is a valid email address. For a password, we'll ask for something at least 8 characters long and including one letter, one number, and one special character. (Yes, this is not really the best way to write strong passwords; but for the sake of showing off how Zod works, we're going with it.) We'll also ask the user to confirm their password by typing it twice. First, let's create a Zod schema to model these inputs: ` So far, this schema is pretty basic. It's only making sure that whatever the user types as an email is an email, and it's checking that the password is at least 8 characters long. But it is *not* checking if password and confirmPassword match, nor checking for the complexity requirements. Let's enhance our schema to fix that! ` By adding refine with a custom validation function, we have been able to verify that the passwords match. If they don't, parsing will give us an error to let us know that the data was invalid. We can also chain refine functions to add checks for our password complexity rules: ` Here we've chained multiple refine functions. You could alternatively use superRefine, which gives you even more fine grained control. Now that we've built out our schema and added refinements for extra validation, we can parse some user inputs. Let's see two test cases: one that's bound to fail, and one that will succeed. ` There are two main ways we can use our schema to validate our data: parse and safeParse. The main difference is that parse will throw an error if validation fails, while safeParse will return an object with a success property of either true or false, and either a data property with your parsed data or an error property with the details of a ZodError explaining why the parsing failed. In the case of our example data, userInput2 will parse just fine and return the data for you to use. But userInput1 will create a ZodError listing all of the ways it has failed validation. ` ` We can use these error messages to communicate to the user how they need to fix their form inputs if validation fails. Each error in the list describes the validation failure and gives us a human readable message to go with it. You'll notice that the validation errors for checking for a valid email and for checking password length have a lot of details, but we've got three items at the end of the error list that don't really tell us anything useful: just a custom error of Invalid input. The first is from our refine checking if the passwords match, and the second two are from our refine functions checking for password complexity (numbers and special characters). Let's modify our refine functions so that these errors are useful! We'll add our own error parameters to customize the message we get back and the path to the data that failed validation. ` Now, our error messages from failures in refine are informative! You can figure out which form fields aren't validating from the path, and then display the messages next to form fields to let the user know how to remedy the error. ` By giving our refine checks a custom path and message, we can make better use of the returned errors. In this case, we can highlight specific problem form fields for the user and give them the message about what is wrong. Integrating with TypeScript Integrating Zod with TypeScript is very easy. Using z.infer<typeof YourSchema> will allow you to avoid writing extra TypeScript types that merely reflect the intent of your Zod schemas. You can create a type from any Zod schema like so: ` Using a TypeScript type derived from a Zod schema does *not* give you any extra level of data validation at the type level beyond what TypeScript is capable of. If you create a type from z.string.min(3).max(20), the TypeScript type will still just be string. And when compiled to JavaScript, even that will be gone! That's why you still need to use parse/safeParse on incoming data to validate it before proceeding as if it really does match your requirements. A common pattern with inferring types from Zod schemas is to use the same name for both. Because the schema is a variable, there's no name conflict if the type uses the same name. However, I find that this can lead to confusing situations when trying to import one or the other—my personal preference is to name the Zod schema with Schema at the end to make it clear which is which. Conclusion Zod is an excellent tool for easily and confidently asserting that the data you're working with is exactly the sort of data you were expecting. It gives us the ability to assert at runtime that we've got what we wanted, and allows us to then craft strategies to handle what happens if that data is wrong. Combined with the ability to infer TypeScript types from Zod schemas, it lets us write and run more reliable code with greater confidence....

Nov 15, 2024

7 mins

JavaScriptZod

Building a Stripe App: A Step-by-Step Guide to QR Code Generation

Building a Stripe App: A Step-by-Step Guide to QR Code Generation Why Build a Stripe App? I recently participated in an audio space with the Stripe team, and something they said really stuck with me: the Stripe app store is a growing area that isn't overly saturated yet. There's a lot of potential for new apps, and companies can use this opportunity to grow. I work at a company called This Dot Labs, and we've created several Stripe apps and even own one. After looking at the data, I can confirm that the Stripe team was right! Creating a QR Code Generator App For this tutorial, we'll build a QR code app that can take a URL and generate a code for it. This is a good use case to help you understand the ins and outs of Stripe's developer tools. Why QR Codes? QR codes are useful tools that have become common in e-commerce, restaurants, and other industries. While Stripe already has a QR code tool, we'll make our own to familiarize ourselves with their syntax and problem-solving approaches. Project Structure Before we dive into the implementation, let's look at the structure of our Stripe App QR Code project: * .vscode: Contains settings for Visual Studio Code * source/views: Holds the main application views * .gitignore: Specifies files to ignore in version control * stripe-app.json: Defines the Stripe app configuration * ui-extensions.d.ts: TypeScript declaration file for UI extensions * .build: this is where the built Stripe app gets placed. Step-by-Step Implementation 1\. Install Stripe Locally First, you need to install Stripe on your local machine. The documentation provides great instructions for this: * For Mac users: Use Brew to install * For Windows users: Download the package and add it to your environment variables You can find the details here in the stripe docs to install the Stripe CLI https://docs.stripe.com/stripe-cli When using Windows, you must do stripe login from Powershell, NOT from Git bash or any other tool. After the server is up, then you can continue using git bash for everything else. After stripe login, you need to enter stripe apps start. Once you do that, the server is up and running and you can go back to using git bash or any other tool. 2\. Install Dependencies We'll be using an extra package for QR code generation. Install it using npm: ` 3\. Set Up the Main Component Let's look at the home.tsx file, where we'll use Stripe's UI components: ` These components are similar to other UI libraries like Bootstrap or Tailwind CSS. 4\. Create the UI Structure Our app will have: * An input field for the URL * Validation using a regex pattern * Error handling for invalid URLs * QR code generation and display Here is the Home.tsx file that is located in the src/views folder ` * ContextView` is at the top level of the app where we see the Title and the link to the Stripe Docs that we placed in our Context View. * Box is how you use Divs. * Banners can be used to show notification errors or any other item you wish to display. * Textfields are input fields. * Everything else is pretty self-explanatory. 5\. Handle Content Security Policy One problem I personally ran into was when I tried to redirect users, the Stripe policies would block it since I did not express that I knew what it was doing. I had to go into the stripe-app.json file and mention the specific security policies. For this particular exercise, I kept these as null. This is my stripe-app.json file. ` 6\. Configure App Views As you can see here, the stripe-app.json file shows the views for each file I have. The Home.tsx file and the Invoice.tsx are also included This is our way of saying that for each view we have, show the app functionality on that page. Our stripe-app.json file will show it but also, the manifest.js file in our .build folder will also show the same. Any view that doesn't have a file will not show the application's functionality. So, if I were to go to transactions, the app would not show the same logic as the home or invoices page. By following these steps, you'll have a fully functional QR code generator app for Stripe. This is just a simple example, but the potential for Stripe apps is massive, especially for businesses serving e-commerce customers. If you need help or get stuck, don't hesitate to reach out, danny.thompson@thisdot.co. The Stripe team is also very active in answering questions, so leverage them as a resource. Happy coding!...

Dec 18, 2024

4 mins

stripe

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Getting Started with Angular & Apollo

Setup

Create the App

Adding Apollo

Adding Angular Material Styling

Getting Calendar Events

Creating the calendar-event module

Calendar Event Models

GraphQL Queries

Adding Queries in Apollo Angular

Creating a Calendar Event

GraphQL Mutations

Adding Mutations in Apollo Angular

Conclusion

References

You might also like

SSR Finally a First-Class Citizen in Angular?

Using HttpClient in Modern Angular Applications

Introduction to Zod for Data Validation

Building a Stripe App: A Step-by-Step Guide to QR Code Generation

Let's innovate together!

You might also like

SSR Finally a First-Class Citizen in Angular?

Using HttpClient in Modern Angular Applications

Introduction to Zod for Data Validation

Building a Stripe App: A Step-by-Step Guide to QR Code Generation