Forem: Robin Goetz

spartan enters a new era with Zerops

Robin Goetz — Tue, 12 Nov 2024 18:21:31 +0000

A Game-Changing Partnership

I’m beyond excited to share that spartan has partnered with Zerops, a developer-first cloud platform deeply rooted in Angular and committed to strengthening its ecosystem. This collaboration is a huge opportunity for spartan, giving us the momentum and sustainability we need to take the project to the next level.

Community Growth and the Need for Sustainability

Over the last few months, development has been slower than I’d hoped—balancing life and other commitments can do that—but the growth of the spartan community has been nothing short of incredible. We’re now approaching 1,500 GitHub stars and seeing 2,400+ weekly downloads, a clear signal that developers see the value in what we’re building.

This partnership with Zerops enables us to meet that demand head-on. For the first time, we’re able to compensate our team of core developers, ensuring they can dedicate more time to creating, refining, and expanding the spartan/ui components. These are people who care deeply about what we’re building, and now, they’ll have the resources to deliver their best work sustainably.

Why Zerops?

If you’re familiar with Zerops, you know they’re no strangers to Angular. Their support of projects like AnalogJs demonstrates their commitment to the ecosystem, and their alignment with spartan’s values—modern, accessible, flexible tools to build Angular apps—makes them the perfect partner for this journey.

What’s Next: A Production-Ready Starter Template

One of the first outcomes of this partnership will be a starter template that integrates spartan with the Medusa e-commerce platform. This isn’t just a proof of concept—it’s a production-ready starting point for building e-commerce applications, combining spartan/ui components, Analog's full-stack capabilities, Medusa’s powerful platform, and Zerops’ seamless deployment tools.

Celebrating the spartan Community

Of course, none of this would be possible without the incredible spartan community. From day one, The 300—our contributors—have been at the heart of everything we do. Your contributions, feedback, and ideas have shaped spartan into what it is today. This partnership with Zerops isn’t just about expanding the project—it’s about honoring the work and support that’s come before.

The Road Ahead

Looking ahead, the future of spartan is bright. Whether you’re a long-time supporter or just discovering the project, now is the perfect time to get involved. Check out the GitHub, explore the roadmap, or contribute and become part of The 300. Together, we’re continuing to build towards an even more sustainable, accessible future for Angular development.

This is your sign(al) to try TanStack Query & Angular

Robin Goetz — Tue, 05 Mar 2024 15:20:39 +0000

In version 16, Angular released signals. A reactive primitive promised by the core team that would help take the framework to the next level. A primitive that allows for fine-grained rendering updates and a world where Angular is not reliant on ngZone for change detection anymore. A primitive that also provides the open source ecosystem with a new way to react to changes in values in components, directives, and services.

Now about 7 months later, the Angular community has absolutely embraced the signals sent by the core team and is building incredible new tools and libraries on top of this new technology.

Projects like ngrx/signals, ngxtension with signalSlice or combine, come to mind immediately.

But not only do signals enable new innovation inside the existing ecosystem, they also enable developers to port incredibly powerful solutions to Angular. By leveraging signals and their new way of notifying and reacting to changes in values that is significantly less complex than RxJs.

One of these projects, and the one that I am (currently) most excited about is arnoud-dv's official adapter that brings TanStack Query to the Angular ecosystem.

In this article, I'll introduce TanStack Query and try make this your sign(al) to give TanStack Query & Angular a try!

What is TanStack Query?

TanStack Query is a data-fetching library that originated in the React ecosystem. It is an opinionated tool that allows you to easily fetch, cache, synchronize and update server state in web applications.

If you have worked on bigger Angular applications, you probably realized that while the framework provides its own HttpClient to fetch remote data, it does not come with an opinionated way of managing the state of those interactions. We might create our own solutions with global NgRx or NGXS stores that allow us to access server data, let us manage entity collections, and manually trigger requests to fetch new information whenever it's necessary. Maybe we even develop some sort of opinionated meta-server-state-management tool to bring some order to the chaos.

However, while NgRx, NGXS, or Elf are powerful state management libraries, they were often created for working with client state and not explicitly designed around managing asynchronous or server state.

What is server state?

Let's look at how the TanStack Query team defines it:

For starters, server state:

Is persisted remotely in a location you do not control or own
Requires asynchronous APIs for fetching and updating
Implies shared ownership and can be changed by other people without your knowledge
Can potentially become "out of date" in your applications if you're not careful

This (unsurprisingly) makes perfect sense. Our data often lives in a remote database, not in the browser. To access and alter this data we need to communicate with our servers through API calls. These calls are always asynchronous. Others often have access to the same data. This means that although we might have just fetched a local copy of the data from the API, someone else could have already changed the underlying record in the database.

Bummer... Looks like managing server state is actually a lot more complex than calling this.http.post.

As we grasp this nature of server state in our applications, the TanStack team points out that even more challenges will inevitably arise as we go:

Caching... (possibly the hardest thing to do in programming)
Deduping multiple requests for the same data into a single request
Updating "out of date" data in the background
Knowing when data is "out of date"
Reflecting updates to data as quickly as possible
Performance optimizations like pagination and lazy loading data
Managing memory and garbage collection of server state
Memoizing query results with structural sharing

Oof...

Just reading these points makes all my alarm signals go off and scream: Complexity!! Don't get me wrong, every once in a while I like a technical challenge (like building spartan/ui), but this just seems like an absolute nightmare to deal with...

Especially, if there already exists a battle tested server state-management solution that let's you "[t]oss out that granular state management, manual refetching and endless bowls of async-spaghetti code [and] gives you declarative, always-up-to-date auto-managed queries and mutations that directly improve both your developer and user experiences."

I love declarative solutions to complex problems. Even more those that people that are a lot smarter than me built with all the different edge cases in mind. Those solutions that let us use the fruits of years of their hard work so we can focus on building OUR applications.

I love TanStack Query!

It's all about the Queries!

As the name already implies TanStack Query is built around the concept of Queries. The library takes care of all the complexities of fetching the data for these queries, manages updating the data, and can notify you when the data becomes out of date, and so much more.

Let's start with taking a look at an example of a simple query that fetches data about the TanStack Query GitHub repository:

import { ChangeDetectionStrategy, Component, inject } from '@angular/core'
import { HttpClient } from '@angular/common/http'
import { CommonModule } from '@angular/common'
import { injectQuery } from '@tanstack/angular-query-experimental'
import { lastValueFrom } from 'rxjs'

@Component({
  changeDetection: ChangeDetectionStrategy.OnPush,
  selector: 'simple-example',
  standalone: true,
  template: `
    @if (query.isPending()) {
      Loading...
    }
    @if (query.error()) {
      An error has occurred: {{ query.error().message }}
    }
    @if (query.data(); as data) {
      <h1>{{ data.name }}</h1>
      <p>{{ data.description }}</p>
      <strong>👀 {{ data.subscribers_count }}</strong>
      <strong>✨ {{ data.stargazers_count }}</strong>
      <strong>🍴 {{ data.forks_count }}</strong>
    }
  `,
})
export class SimpleExampleComponent {
  http = inject(HttpClient)

  query = injectQuery(() => ({
    queryKey: ['repoData'],
    queryFn: () =>
      lastValueFrom(
        this.http.get<Response>('https://api.github.com/repos/tanstack/query'),
      ),
  }))
}

This code is all that is needed to fetch the data, cache it effectively, and have all the challenges of managing server state we explored above to be taken care of for us.

We only give TanStack Query, using the injectQuery function, a unique identifier, the queryKey, for the data we are interested in and then tell it how to fetch the data with a queryFn.

With this in mind, let's dig a little deeper and try to understand what makes TanStack Query tick (no change detection pun intended.)

So what is a Query again?

From the docs:
A query is a declarative dependency on an asynchronous source of data that is tied to a unique key. A query can be used with any Promise based method (including GET and POST methods) to fetch data from a server.

This explains the two options we see getting passed to injectQuery in our example:

queryKey: ['repoData'],
queryFn: () => lastValueFrom(this.http.get<Response>('https://api.github.com/repos/tanstack/query')),

The ['repoData'] array is used as a unique query key. This key is associated with a "container" that holds all the data associated with the state & data of our query. If you are wondering why this key is an array and not a simple string, worry not. We will go into more detail on this in a second.

To update our query's data we need a promised based method to fetch data from the server, the queryFn. In Angular interactions with the server happen through the HttpClient. Because the HttpClient returns an Observable we are using lastValueFrom to make our server client interaction promise based:

() => lastValueFrom(this.http.get<Response>('https://api.github.com/repos/tanstack/query'))

The query result, which is returned by the injectQuery function, contains all of the information about the query that you'll need for templating and any other usage of the data as we can see in our example's template:

@if (query.isPending()) {
  Loading...
}
@if (query.error()) {
  An error has occurred: {{ query.error().message }}
}
@if (query.data(); as data) {
  <h1>{{ data.name }}</h1>
  <p>{{ data.description }}</p>
  <strong>👀 {{ data.subscribers_count }}</strong>
  <strong>✨ {{ data.stargazers_count }}</strong>
  <strong>🍴 {{ data.forks_count }}</strong>
}

The query object contains a few very important states you'll need to be aware of to be productive. A query can only be in one of the following states at any given moment:

isPending or status === 'pending' - The query has no data yet
isError or status === 'error' - The query encountered an error
isSuccess or status === 'success' - The query was successful and data is available

Beyond those primary states, more information is available depending on the state of the query:

error - If the query is in an isError state, the error is available via the error property.
data - If the query is in an isSuccess state, the data is available via the data property.
isFetching - In any state, if the query is fetching at any time (including background refetching) isFetching will be true.

Why is our queryKey an array?

So far so good, we know that injectQuery gives us an optimized way to store server-state for a query key and an associated promised based server-client interaction, but why do we use an array as a key? Wouldn't a string make more sense?

When in doubt, take a look at TanStack Query's incredible docs. They state the following:

At its core, TanStack Query manages query caching for you based on query keys. Query keys have to be an Array at the top level, and can be as simple as an Array with a single string, or as complex as an array of many strings and nested objects. As long as the query key is serializable, and unique to the query's data, you can use it!

While there might be some hints on why you'd want unique and serializable keys, this alone does not yet tell me why they decided to go with an Array instead of using strings. Let's look at a couple examples to understand this decision.

For the simplest of use cases such as generic lists or non-hierarchical resources a simple string would probably work.

// A list of todos
injectQuery({ queryKey: ['todos'], ... })

// Something else, whatever!
injectQuery({ queryKey: ['something', 'special'], ... })

However, keeping them as an array will be well worth it! In reality our queries often need more information to uniquely describe their data. That is the reason we are using an array for our query keys. We can now combine strings and any number of serializable objects to describe our data:

// An individual todo
injectQuery({ queryKey: ['todo', 5], ... })

// An individual todo in a "preview" format
injectQuery({ queryKey: ['todo', 5, { preview: true }], ...})

// A list of todos that are "done"
injectQuery({ queryKey: ['todos', { type: 'done' }], ... })

As you see, when we deal with hierarchical or nested resources, and pass an ID, index, or other primitive to uniquely identify the item, or deal with
queries that rely on additional search parameters, the array approach and its intrinsic hierarchy shines.

Important to remember: Because query keys uniquely describe the data they are fetching, they always should include any variables you use in your query function that change.

Why do we need a function to return our options instead of passing them in directly?

The tl;dr is that we can think of the function we are using to pass in our options as an effect for Angular's signals. That means the options are now updated whenever one of the signals used to construct them changes. Our query starts to react to the signals we use to declare it.

Let's take a closer look how we ended up with this signal powered approach.

Origins of TanStack Query in React

TanStack Query originated as a React data fetching library.

In React world everything is a component. There is no concept of services or directives. Your application is ultimately composed of only components. React re-renders a component whenever one of it's props, which are values passed directly to the component, or some local state, declared with useState, change.

React does not have a dependency injection mechanism in the same way Angular does. Instead it relies on a concept called hooks, e.g. useQuery. These hooks are functions that are re-executed whenever the component they are called from is re-rendered.

TanStack Query manages all of it's server state outside of the React application.

import {
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'
// Create a client outside of the React App
const queryClient = new QueryClient()

function App() {
  return (
    // Provide the client to your App
    <QueryClientProvider client={queryClient}>
      <Todos />
    </QueryClientProvider>
  )
}

It also does the same in Angular. To make our example from earlier work, we actually need to create the QueryClient as a global object and provide it when bootstrapping our Angular application:

import { provideHttpClient } from '@angular/common/http'
import {
  provideAngularQuery,
  QueryClient,
} from '@tanstack/angular-query-experimental'

const queryClient = new QueryClient();

bootstrapApplication(AppComponent, {
  providers: [provideHttpClient(), provideAngularQuery(queryClient)],
})

The code to setup TanStack Query with React and Angular actually look pretty similar. Both times TanStack's QueryClient is instantiated outside the actual application. The core of it is framework agnostic.

However, to take advantage of all the benefits TanStack provides for server-state management we need to connect this queryClient with our application.

In React we do this with the useQuery hook to which we pass our query keys. Hooks are re-rendered when components input props or state changes. If a query key depends on props or state, the query key changes, which in return propagates the change to the queryClient:

function Todos() {
  const [page, setPage] = useState(0);
  const query = useQuery({ queryKey: ['todos', page], queryFn: getTodos })

  return (
      <ul>{query.data?.map((todo) => <li key={todo.id}>{todo.title}</li>)}</ul>
  )
}

Reactive Angular

In Angular on the other hand, not everything is a component and there is no concept of a component tree re-rendering. Instead Angular comes with it's own Change Detection Mechanism based on ngZone. For TanStack Query this means that the simple paradigm of input change or (non reactive) state change triggers function call with new param, which changes query key which causes TanStack Query to do its magic, does not work anymore.

However, this reaction to an input or state change does sound suspiciously familiar to what effect's do with signals. And while the specifics are more complicated this is actually a good first intuition of how signals allow such an intuitive port to Angular:

@Component({
  changeDetection: ChangeDetectionStrategy.OnPush,
  selector: 'todos',
  standalone: true,
  template: `
  <ul>
    @for(todo of query.data() ?? []; track todo.id) {
      <li>{todo.title}</li>
    }
  </ul>
  `,
})
export class TodosComponent {
  page = signal(0)
  query = injectQuery(() => ({
    queryKey: ['todos', page()],
    queryFn: () => getTodos(this.page()))
}

Whenever the page variable, a "simple" state value in React or a signal containing state in Angular, changes. The TanStack Query client is made aware of this page change. The query key that is composed of the page value is updated, and the associated data is refetched accordingly.

As @arnouddv pointed out, there is another reason to return the options from a function:

[Returning options from a functions] allows to preserve expressions. JavaScript - like most languages, is eagerly evaluated. The only practical way to preserve expressions is to wrap them in a function.

Which allows code like this:

postQuery = injectQuery(() => ({
    // ...
    enabled: this.postId() > 0
}))

Which means the query will be automatically enabled for you whenever the postId signal value is greater than 0. No need to separately define and pass a computed signal. This works for all the query properties.

If it becomes more complex than a simple comparison or maybe a ternary I would recommend a separate computed for code readability though.

Mutations: Update the server, invalidate the client

Now that we have a better understanding of how we can leverage queries to fetch and manage async server state, we take a closer look and updating server state, and how we can ensure that these updates are also reflected in our client side data.

To create/update/delete data or perform server side-effects, TanStack Query introduces the concept of mutations and exports a injectMutation function to carry them out.

For example if you wanted to create a new todo on the server you could use a mutation like this:

@Component({
  template: `
    <div>
      @if (mutation.isPending()) {
        <span>Adding todo...</span>
      } @else if (mutation.isError()) {
        <div>An error occurred: {{ mutation.error()?.message }}</div>
      } @else if (mutation.isSuccess()) {
        <div>Todo added!</div>
      }
      <button (click)="mutation.mutate(1)">Create Todo</button>
    </div>
  `,
})
export class TodosComponent {
  todoService = inject(TodoService)
  mutation = injectMutation(() => ({
    mutationFn: (todoId: number) =>
      lastValueFrom(this.todoService.create(todoId)),
  }))
}

The mutation object contains the same state indicators as a query. isIdle, isPending, isError, isSuccess, error, and data.

It also has a mutate function, which triggers the mutationFn that we pass into the injectMutation's options object. In the example above, a click on the Create Todo button starts executing our mutation. You can also see that variables can be passed to our mutations function by calling the mutate function with a single variable or object.

It is sometimes the case that you need to clear the error or data of a mutation request. To do this, each mutation has a reset function, which can be called to handle this.

Overall, mutations are actually a lot more straightforward than queries. However, it is often the case that after mutating some state on the server, we need to make sure that our queries reflect those changes on the frontend. To do that, we can pass an onSuccess function to the injectMutation options object. This function is called after the mutation successfully completed, which means it is the perfect place to ensure that your frontend data is up to date.

There are two ways we can make this happen:

We invalidate the query keys that we know are affected by our mutation and let TanStack Query handle the refetching of the data. This shows the true power of declarative server-state management that is completely driven by query keys.

export const injectAddComment = (id: string) => {
  const http = inject(HttpClient);
  const queryClient = injectQueryClient();
  return injectMutation((client) => ({
    mutationFn: (newComment: string) =>
      lastValueFrom(
        http.post(`/posts/${id}/comments`, newComment)
      ),
    // Invalidate and refetch by using the client directly
    onSuccess: () => {
      // ✅ refetch the comments list for our blog post
      queryClient.invalidateQueries({
        queryKey: ['posts', id, 'comments']
      })
    },
  }));
};

Internally, TanStack Query uses fuzzy matching on the query key. That means that if you have multiple keys for your comments list, they will all be invalidated. Only currently active keys will be refetched, others are marked as stale and refetched the next time they are used.

Let's say we have the option to sort our comments. When the new comment was added, two queries with comments are in our cache:

['posts', 5, 'comments', { sortBy: ['date', 'asc'] }
['posts', 5, 'comments', { sortBy: ['author', 'desc'] }

We're only displaying one of them on the screen. invalidateQueries refetches that one and marks the other one as stale. The user will always see the latest data.

We know exactly what data on the frontend needs to be updated as a result of our mutation and set the new data directly inside our query client. This should be used with caution, but does avoid another (background) API call to our server.

export const injectUpdateTitle = (id: string) => {
  const http = inject(HttpClient);
  const queryClient = injectQueryClient();
  return injectMutation((client) => ({
    mutationFn: (newTitle: string) =>
      lastValueFrom(
        http.post(`/posts/${id}`, {
          title: newTitle,
        })
      ),
    // Invalidate and refetch by using the client directly
    onSuccess: (newPost: Post) => {
      // ✅ update detail view directly
      queryClient.setQueryData(['posts', id], newPost)
    },
  }));
};

Putting data into the cache directly via setQueryData will act as if this data was returned from the backend. All components using that query will update accordingly.

Invalidation should be preferred and while it depends on the use-case, for direct updates to work reliably, you need more code on the frontend, and to some extent duplicate logic from the backend. For example, sorted lists are pretty hard to update directly. The position of the entry could've potentially changed due to the update. Invalidating the whole list is most often the "safer" approach.

Is TanStack Query for components only or do directives and services work too?

Since directives are just components without templates, the same code, for queries and mutations, that we used in our examples above would also work in any directive.

Even more important to understand is that TanStack Query actually does not care where it is used. As we saw above, TanStack Query manages our server-state outside of our Angular application. The only limitation on where to use Angular Query is that the injectQuery function needs to be called from an injection context.

This is actually an Angular dependency injection limitation. However, since the instantiation of a class is run in an injection context it feels very natural to declare the query variable as a class variable. However, if you want to learn more about Angular's injection context I recommend this article.

Finally, the injectQuery function provides all it's internal state and data as signals. We can use those signals to integrate with other code of any of our components, including the template, directives or services.

How I use TanStack Query with modern Angular

Write Reusable Queries with Custom Injection Functions

When I started using TanStack Query for my Angular applications, I quickly realized that I do not always want to have to rewrite the same queryKey and queryFn everywhere. This seems like a great way to introduce inconsistencies and bugs that are hard to debug. What I wanted is a way to reuse queries.

This is where we can leverage the power of custom injection functions (CIF) and inject reusable queries. To these CIFs I like to pass in a params signal that drives the query, and an optional injector, which allows users to leverage the CIF is places where no injection context is available. I highly recommend reading this article by Chau, if you want to learn more about the reasoning behind this.

Putting these ideas together, the source code for a reusable query looks like this:

import { inject, Injector, runInInjectionContext } from '@angular/core';
import { assertInjector } from 'ngxtension/assert-injector';
import { HttpClient } from '@angular/common/http';
import { injectQuery } from '@tanstack/angular-query-experimental';
import { lastValueFrom } from 'rxjs';
import { todoKeys, ToDo } from './todos.keys';

export const injectTodosQuery = (params: Signal<{ done?: boolean }>,{ injector }: { injector?: Injector } = {}) => {
  injector = assertInjector(injectTodosQuery, injector);
  return runInInjectionContext(injector, () => {
    const http = inject(HttpClient);
    return injectQuery(() => ({
      queryKey: todoKeys.list,
      queryFn: () => lastValueFrom(http.get<ToDo[]>(`todos?done=${!!params().done}`)),
    }));
  });
};

Where the assertInjector function from ngxtension looks like this:

export function assertInjector(fn: Function, injector?: Injector): Injector {
    // we only call assertInInjectionContext if there is no custom injector
    !injector && assertInInjectionContext(fn);
    // we return the custom injector OR try get the default Injector
    return injector ?? inject(Injector);
}

It can be consumed in any component, directive, or service. With the optional Injector you can now delay injecting the query until you need it, e.g. after Inputs become available in ngOnInit.

Read the docs & TkDodo's blog

Besides these "Angular specific" challenges, I try to study and emulate all the pattern's that the TanStack documentation lays out or find myself reading the incredible blog posts @tkdodo has published on his personal blog! So far they have an answer to any question I could ever have about TanStack Query.

Here are some insights I consider absolutely essential from his blog:

Always keep good Query Keys hygiene

Keep your Query Keys next to their respective queries, co-located in a feature directory or Nx library:

- src
  - app
    - features
      - todos
        - todos.keys.ts
        - todos.mutations.ts
        - todos.query.ts

Structure your Query Keys from most generic to most specific, with as many levels of granularity as you see fit in between. Here's an example structure for a todos list that allows for filterable lists as well as detail views:

['todos', 'list', { filters: 'all' }]
['todos', 'list', { filters: 'done' }]
['todos', 'detail', 1]
['todos', 'detail', 2]

So far we have been manually declaring the Query Keys a lot. This error-prone and makes changes harder in the future if you wanted to add another level of granularity to your keys.

@tkdodo recommends to use Query Key factory per feature: A simple object with entries and functions that will create query keys. For the above structure, it would look like this:

const todoKeys = {
  all: ['todos'] as const,
  lists: () => [...todoKeys.all, 'list'] as const,
  list: (filters: string) => [...todoKeys.lists(), { filters }] as const,
  details: () => [...todoKeys.all, 'detail'] as const,
  detail: (id: number) => [...todoKeys.details(), id] as const,
}

But don't take my word for this and read Dominik's article that goes into much more detail.

Keep this in mind to master mutations

injectQuery is declarative, injectMutation is imperative.

TanStack's Queries mostly run automatically. We define the dependencies, but TanStack Query takes care of running the query immediately. It also performs smart background updates when necessary. This works great for queries because we want to keep what we see on the screen in sync with the actual data on the backend.

For mutations, this doesn't make sense: Imagine a new todo is created every time the user focuses their browser window... Thus, instead of running a mutation instantly, TanStack Query gives us a function that can be invoked whenever we want to make the mutation.

For this reason, mutations also do not share state like injectQuery does. You can use injectQuery multiple times in different components and will get the same, cached results. This is not the same for injectMutation. Each time you will get a new mutation, which keeps track of its own state and can be triggered with it's mutate-method.

Be aware of `await`-ed Promises

Promises returned from the mutation callbacks are awaited by TanStack Query. invalidateQueries returns a Promise. If you want your mutation to stay in loading state while your related queries update, you have to return the result of invalidateQueries from the callback!

Know when to use `mutate` or `injectMutation` callbacks

You can have callbacks on injectMutation as well as on mutate itself. Know that the callbacks on injectMutation fire before the callbacks on mutate. Callbacks on mutate might not fire at all if the component/directive/service is destroyed before the mutation has finished.

It's good practice to separate concerns in your callbacks:

Do things that are absolutely necessary and logic related (like query invalidation) in the injectMutation callbacks.
Do UI related things like redirects or showing toast notifications in mutate callbacks. If the user navigates away from the current screen before the mutation finishes, those will purposefully not fire.

// always, declared in the Custom Injection Function (CIF)
const injectUpdateTodo = () => {
  const queryClient = injectQueryClient();
  return injectMutation({
    mutationFn: updateTodo,
    // ✅ always invalidate the todo list
    onSuccess: () => {
      queryClient.invalidateQueries({
        queryKey: ['todos', 'list']
      })
    },
  })
}

// in the component
private updateTodo = injectUpdateTodo();
...
updateTodo.mutate(
  { title: 'newTitle' },
  // ✅ only redirect if we're still on the detail page
  // when the mutation finishes
  { onSuccess: () => router.navigate(['todos']) }
)

This separation is especially neat if injectMutation is part of a Custom Injection Function, CIF. The CIF contains all query related logic while UI related actions come from the component driving the UI. This also makes the CIF more reusable, because how you interact with the UI might vary on a case by case basis - but the invalidation logic will likely always be the same!

Again, do yourself a favor and read this this incredible article by @tkdodo.

Got a question? Read the FAQs!

As you dive deeper into TanStack Query and are starting to use it for more advanced use cases you will inevitably end up with a bunch of questions. It's new technology after all. However, us Angular developers have a huge advantage, because TanStack Query has been used in the React community for years most, if not all, of your questions have already been asked, and answered! Dominik again, did us a huge favor and consolidated answers to the most frequent questions in this great article.

Why introduce another dependency?

Yes, TanStack Query does come with a learning curve. However, I would describe this learning curve more as a period of unlearning async state micro-management and replacing it with a straightforward concept of hierarchical query keys, declarative data fetching in components, and knowing when to invalidate queries of which we know the server data has changed.

If you decide to add TanStack Query to your application, it will very likely:

Help you remove many lines of complicated and misunderstood code from your application and replace with just a handful of lines of TanStack Query logic.
Make your application more maintainable and easier to build new features without worrying about wiring up new server state data sources
Have a direct impact on your end-users by making your application feel faster and more responsive than ever before.
Potentially help you save on bandwidth and increase memory performance.

So it's up to you. Is it worth adding another dependency?

So this replaces NgRx right?

No, but it will greatly reduce code you have to write yourself to manage server state. I went into great detail in the beginning describing all the requirements one has to consider when developing a solution that adequately and declaratively manages server state. Imagine yourself (re-)implementing an NgRx store that takes care of everything above.

Don't do that to yourself. The creators of TanStack Query already built an amazing solution that deals with complexities of managing server state for you. It works amazingly well out-of-the-box, with zero-config, and can be customized to your liking as your application grows.

What TanStack Query does not do for you is manage your application's global client state. It is simply not built to keep track of a complex chain of UI interactions, which we so often deal with in enterprise applications, or knows how to keep track of changes to an in memory list of elements that we are reordering with drag and drop, whose names and descriptions we can edit, all before hitting save. That's where NgRx and all the other client state libraries of the Angular ecosystem shine and will continue to be our trusted companions.

What's next?

I highly recommend all of you to check out the TanStack Query documentation. It is incredibly good and gives you everything to get up and running in no time.

Even better, if there is any question left unanswered by the official documentation you can bet that @tkdodo has written post on his blog about the topic that explains and demonstrates the concept in a way that is absolutely incredible!

If you want to get a more thorough Angular specific introduction, this article by Tomasz Ducin is well worth the read!

Keep in mind that the Angular port is currently in an experimental stage. Breaking changes can still happen in any release and we are using this incredible piece of code at our own risk.

However, the core of TanStack Query is in it's 5th major version already. It's battle tested in millions of production apps and finally making its way to the Angular ecosystem.

To ensure that we get the best TanStack Query experience possible we are also encouraged to share feedback and participate in the discussion on GitHub, which you can check out here!

So what are you waiting for? Give TanStack Query a try and never look back! I have been using it for a few weeks now and am already absolutely hooked!

This is your sign(al) to try TanStack Query & Angular!!!

As always, do you have any further questions? What do you think of TanStack Query? Could you see yourself adding it to your project? Do you think you'd need to see an example app where queries and mutations are used in components, directives, or services? Do you have any other topics you'd like me to write about? I am curious to hear your thoughts. Please don't hesitate to leave a comment or send me a message.

Finally, if you liked this article feel free to like and share it with others. If you enjoy my content follow me on Twitter or GitHub.

Getting Started with spartan/ui - Shadcn-like UI Components for Angular

Robin Goetz — Thu, 24 Aug 2023 16:04:02 +0000

We're all familiar with this: We are starting a new project and are looking for some beautiful UI components. While we could technically build these from scratch, we want to start building instead of reinventing the wheel. We need a solution to hit the ground running without sacrificing quality or accessibility (a11y).

So we venture into the world of Angular component libraries.
While they all provide incredible variety and most of them come with solid accessibility features, it seems that most Angular UI libraries come with a strong corporate branding that often doesn't quite align with the project's needs. More importantly, they mostly lack an easy way to customize or extend components and do not allow us to let them make them our own.

Then we look at the React ecosystem and all the incredible projects built on RadixUI and shadcn. I don't know about you, but when I do that I always get a little jealous.

shadcn - A game-changing UI library (for React)

Why? shadcn/ui comes with all the components you could ever need for a project, and all of them come in beautiful styles by default. However, it still allows you to adjust and customize every single UI primitive as you please.

How does it do that?

It builds on RadixUI, a UI library that is completely un-styled by default, and comes with an intuitive and extensible API, as well as great.
It is styled using TailwindCSS classes and CSS variables that give you the perfect amount of flexibility while pushing you towards using solid design principles.
Instead of making you install the styles through a npm package, it allows you to copy its beautifully crafted primitives directly into your code base, which means you own the code and can adjust everything to fit your needs.

The problem with shadcn for Angular developer's is that it is built on top of React...

Now imagine an accessible, open-source Angular UI library that doesn't come pre-styled, allowing you to have full creative control over its appearance. Angular' shadcn implementation so to say.

spartan/ui - shadcn for Angular

Enter spartan/ui – an innovative collection of Angular UI primitives that are un-styled and accessible by default.

brain & helm - The building blocks of spartan/ui

To achieve our goal of a shadcn-like development experience, spartan/ui comes in two parts:

Through spartan/ui/brain, our goal is to make this process more straightforward and efficient. We offer a versatile collection of un-styled UI building blocks that can be easily tailored to match your project's distinct visual and functional preferences.
With spartan/ui/helm, we provide pre-designed styles built on TailwindCSS and CSS variables. Just like with shadcn, you can copy them into your project so you retain full control over their code, appearance, and overall experience.

@spartan-ng/cli - one command to rule them all

To make this as easy as possible, spartan/ui comes equipped with a CLI that allows you to effortlessly integrate our components into your Nx or Angular workspaces. With a single command, you can add any of its 30+ spartan/ui primitives to your projects.

But that's not all – the CLI's capabilities extend beyond just adding components. You can also leverage it to incorporate one of 12 custom themes into your Angular or Nx applications, letting you truly own the visual appearance of your projects.

Your first spartan app

So let's see what getting up and running with spartan/ui looks like.

If you would rather follow along to a video version of this article, check it out on YouTube.

Setting up an Nx' Angular workspace

As mentioned above, spartan/ui follows the same paradigm as shadcn, that you should own the code that allows you to style, extend, and compose your UI components.

While we are working on a standalone API, Nx provides incredible tooling for exactly this use case. Therefore, the initial version of spartan/ui's CLI is an Nx plugin.

Hence, for this tutorial, we will create a new Angular project inside an Nx workspace.

Running create-nx-workspace

Again, Nx makes this incredibly easy. Simply run the command below.

npx create-nx-workspace@latest

When prompted:

Choose a meaningful name, I chose
Select Angular as your stack.
Opt for a standalone project.
Important: Pick CSS for your styles.
Add an (optional) end-to-end test runner of your choice.
Select standalone components.
Only add routing if you want to.

Finally, wait for Nx to work its magic, install all necessary dependencies, and set up your Angular workspace.

Removing boilerplate

I am a big proponent of having your template and styles in the same file as your Component class. Therefore, I deleted the src/app/app.component.html and src/app/app.component.css files created by the workspace generator. I also got rid of the src/app/nx-welcome.component.ts and changed the contents of my src/app/app.component.ts to the following:

import { Component } from '@angular/core';

@Component({
  standalone: true,
  imports: [],
  selector: 'app-root',
  template: `<button>Hello from {{title}}</button>`
})
export class AppComponent {
  title = 'sparta';
}

One more thing before we are ready to start adding spartan/ui.

Adding TailwindCSS

As spartan/ui is built on top of TailwindCSS, we need a working setup of it for our project.

Thankfully, Nx again makes this incredibly easy for us. Simply run the following command and select your application when prompted:

npx nx g @nx/angular:setup-tailwind

This will create a tailwind.config.ts file and install all the necessary dependencies. Let's continue.

Installing @spartan-ng/cli

We are now ready to add spartan/ui to our project. To make our lives much easier, we will use the Nx plugin, which we install like so:

npm i @spartan-ng/cli

Installing @spartan-ng/ui-core

Then we add the @spartan-ng/ui-core library.

npm i @spartan-ng/ui-core

It contains a bunch of helpers, like the hlm function, which powers our tailwind class merging, and most importantly the @spartan-ng/ui-core/hlm-tailwind-preset, which contains all the necessary extensions to tailwind, which make our spartan/ui/helm directives and components work.

Setting up tailwind.config.js

We now have to add this spartan-specific configuration to your TailwindCSS setup. Simply add @spartan-ng/ui-core/hlm-tailwind-preset to the presets array of your config file:

const { createGlobPatternsForDependencies } = require('@nx/angular/tailwind');
const { join } = require('path');

/** @type {import('tailwindcss').Config} */
module.exports = {
  presets: [require('@spartan-ng/ui-core/hlm-tailwind-preset')],
  content: [
    join(__dirname, 'src/**/!(*.stories|*.spec).{ts,html}'),
    ...createGlobPatternsForDependencies(__dirname),
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

Adding CSS variables

To complete your TailwindCSS setup, we need to add our spartan-specific CSS variables to your style entry point. This is most likely a styles.css in the src folder of your application.

Again, we are using Nx, so our plugin will take care of the heavy lifting:

npx nx g @spartan-ng/cli:ui-theme

When prompted:

Select the only application in the project
Choose a theme you want to try
Select a border-radius you like
Leave the path empty (the plugin should be smart enough to figure out the correct one for most setups)
Leave the prefix empty as we add a default theme

Then, check out your styles.css and see the following spartan/ui-specific variables being added:

:root {
--font-sans: ''
}

:root {
--background: 0 0% 100%;
--foreground: 240 10% 3.9%;
--card: 0 0% 100%;
--card-foreground: 240 10% 3.9%;
--popover: 0 0% 100%;;
--popover-foreground: 240 10% 3.9%;
--primary: 240 5.9% 10%;
--primary-foreground: 0 0% 98%;
--secondary: 240 4.8% 95.9%;
--secondary-foreground: 240 5.9% 10%;
--muted: 240 4.8% 95.9%;
--muted-foreground: 240 3.8% 46.1%;
--accent: 240 4.8% 95.9%;
--accent-foreground: 240 5.9% 10%;
--destructive: 0 84.2% 60.2%;
--destructive-foreground: 0 0% 98%;
--border: 240 5.9% 90%;
--input: 240 5.9% 90%;
--ring: 240 5.9% 10%;
--radius: 0.5rem;
}

.dark {
--background: 240 10% 3.9%;
--foreground: 0 0% 98%;
--card: 240 10% 3.9%;
--card-foreground: 0 0% 98%;
--popover: 240 10% 3.9%;
--popover-foreground: 0 0% 98%;
--primary: 0 0% 98%;
--primary-foreground: 240 5.9% 10%;
--secondary: 240 3.7% 15.9%;
--secondary-foreground: 0 0% 98%;
--muted: 240 3.7% 15.9%;
--muted-foreground: 240 5% 64.9%;
--accent: 240 3.7% 15.9%;
--accent-foreground: 0 0% 98%;
--destructive: 0 62.8% 30.6%;
--destructive-foreground: 0 0% 98%;
--border: 240 3.7% 15.9%;
--input: 240 3.7% 15.9%;
--ring: 240 4.9% 83.9%;
}

Adding our first primitive

Awesome! We are now all set up to use spartan/ui in our project. Let's leverage our Nx plugin one more time and add the button primitive to our project:

npx nx g @spartan-ng/cli:ui button

When prompted:

Select an appropriate directory to put your components, e.g. libs/spartan
Choose the default false, when prompted if you want to skip installing the necessary dependencies

Once the plugin finishes, you will see that a new buildable library was added in your libs/spartan/button-helm folder.

It contains the source code of the HlmButtonDirective, which comes with a bunch of different styles that are applied through a HostBinding based on the different inputs of the directive.

import { Directive, HostBinding, Input } from '@angular/core';
import { cva, VariantProps } from 'class-variance-authority';
import { hlm } from '@spartan-ng/ui-core';
import { ClassValue } from 'clsx';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none ring-offset-background',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
        outline: 'border border-input hover:bg-accent hover:text-accent-foreground',
        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
        link: 'underline-offset-4 hover:underline text-primary',
      },
      size: {
        default: 'h-10 py-2 px-4',
        sm: 'h-9 px-3 rounded-md',
        lg: 'h-11 px-8 rounded-md',
        icon: 'h-10 w-10',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
);
type ButtonVariants = VariantProps<typeof buttonVariants>;

@Directive({
  selector: '[hlmBtn]',
  standalone: true,
})
export class HlmButtonDirective {
  private _variant: ButtonVariants['variant'] = 'default';
  @Input()
  get variant(): ButtonVariants['variant'] {
    return this._variant;
  }

  set variant(value: ButtonVariants['variant']) {
    this._variant = value;
    this._class = this.generateClasses();
  }

  private _size: ButtonVariants['size'] = 'default';
  @Input()
  get size(): ButtonVariants['size'] {
    return this._size;
  }

  set size(value: ButtonVariants['size']) {
    this._size = value;
    this._class = this.generateClasses();
  }

  private _inputs: ClassValue = '';

  @Input()
  set class(inputs: ClassValue) {
    this._inputs = inputs;
    this._class = this.generateClasses();
  }

  @HostBinding('class')
  private _class = this.generateClasses();

  private generateClasses() {
    return hlm(buttonVariants({ variant: this._variant, size: this._size }), this._inputs);
  }
}

Note: Currently the plugin adds dependencies correctly, but their peer dependencies are not installed by Nx
Simply run npm i after the @spartan-ng/cli:ui call to make sure everything is installed correctly.

Using our first primitive

To use our new directive we simply add the directive to our button in our src/app/app.component/ts:

import { Component } from '@angular/core';
import { HlmButtonDirective } from '@spartan-ng/button-helm';

@Component({
  standalone: true,
  imports: [HlmButtonDirective],
  selector: 'app-root',
  template: `<button hlmBtn variant="outline">Hello from {{title}}</button>`
})
export class AppComponent {
  title = 'sparta';
}

Then we start our development server with:

npm start

and see our beautifully styled spartan/ui button:

To change the appearance to another variant we simply add a variant input to our <button hlmBtn>:

import { Component } from '@angular/core';
import { HlmButtonDirective } from '@spartan-ng/button-helm';

@Component({
  standalone: true,
  imports: [HlmButtonDirective],
  selector: 'app-root',
  template: `<button hlmBtn variant="outline">Hello from {{title}}</button>`
})
export class AppComponent {
  title = 'sparta';
}

Our styles will be updated accordingly and we see our outlined button:

Other available components

With the release of the initial alpha version, there are 30 components available:

Accordion
Alert
Alert Dialog
Aspect Ratio
Avatar
Badge
Button
Card
Collapsible
Combobox
Command
Context Menu
Dialog
Dropdown Menu
Input
Icon
Label
Menubar
Popover
Progress
Radio Group
Scroll Area
Separator
Sheet
Skeleton
Switch
Tabs
Textarea (covered by hlmInput directive)
Toggle
Typography

You can add new components the same way as we did for the button. I also plan to create more blog posts and videos, which show how to use spartan/ui to build your user interface.

What's next?

spartan/ui is still in alpha, so there is a long way (a marathon some history nerds might suggest) ahead of us. However, I am super excited that this project is finally getting off the ground and you get to try it out and provide me with incredibly valuable feedback. I hope spartan/ui becomes the shadcn of the Angular ecosystem and together with incredible projects like AnalogJs can bring a similar innovation explosion to all of us.

As always, do you have any further questions or suggestions for blog posts? What do you think of spartan? Could you see yourself adding it to your project? I am curious to hear your thoughts. Please don't hesitate to leave a comment or send me a message.

Finally, if you liked this article feel free to like and share it with others. If you enjoy my content follow me on Twitter or Github.

SPARTAN. Type-safe Angular full-stack development powered by Analog.

Robin Goetz — Tue, 25 Apr 2023 12:07:26 +0000

In 2023, Server-Side Rendering (SSR) is an essential part of modern web applications. In the React ecosystem NextJs has become so incredibly popular that the official React documentation now recommends to use it when creating a new project. The Vue docs point to Nuxt as the recommended way to take a Vue application "from the example to a production-ready SSR app."

So what about Angular? We all know Angular as a popular single page application framework (SPA) by Google. It's strength has always been in enterprise applications, who require developers to build and manage complex systems. But indeed Angular has had support for server side rendering (SSR) through Angular Universal for years. However, in developer surveys Angular's SSR capabilities has been the top area Angular users want to see improvements in. To put it short, SSR is currently one of the weaknesses of this amazing framework. The good news, the team is working hard to bring improvements to Universal and the core framework that will soon allow us to leverage the full power of Angular combined with modern SSR solutions. I invite you to read this exciting article by Jessica Janiuk from the Angular team to learn more.

The even better news is that SSR with Angular today might be a lot further than you think already. @brandontroberts has created an amazing community project called Analog. A metaframework a la NextJs or Nuxt built on top of Angular, Vite, and Nitro. There will be a whole article dedicated to getting started with Analog that will go into much more detail. I also recommend to check out the official documentation at analogjs.org to learn more.

In this article, we will go a step further and augment Analog with some other tools to create a complete, incredibly powerful application stack that is typesafe from the database to the DOM rendering template. Thankfully, Angular's TypeScript support is unrivaled as the framework has been developed entirely in TypeScript since its initial release became available more than ten years ago. To maintain this high focus on typesafety throughout the entire application is only natural. With both client and server written in TypeScript, Analog puts us in an exceptional position to fully capitalize on this, especially as more and more fantastic server side capabilities become available in the Typescript ecosystem.

Once we augment these two fundamental pillars with other amazing (mostly) typesafe technologies we end up with the following stack: Supabase, Prisma, Analog, tRPC, Tailwind, Angular, and Nx. Or short: SPARTAN.

Of course, all the source code is available to you and if you are already excited about this and cannot wait to get your hands dirty I invite you to check out the repository here.

I will do my best to present compelling arguments for each of the underlying technologies. Continue reading to learn why I think they deserve to power your upcoming full-stack application.

The SPARTAN Stack

Let’s get our hands dirty and see the different components that make up the SPARTAN stack:

Nx

Let's start with the workspace. The location where your code will reside and the features that meet the needs of your users will be implemented. It reminds me of a craftsman's workshop, if you will. There is only a workbench at first, and as you move along and continue working on your projects, you gradually fill it with all the tools you need. Our beloved uncle Nx has been doing woodworking for years and arrives on the first day with a toolbox filled with every tool one could ever need. But let’s get back to software:

Nx is a next-generation build system that offers first-class monorepo support and strong integrations for all well-known javascript frameworks. It enables you to use frontend frameworks like Angular or backend frameworks like NestJs to architect, test, and build your project at any size.

It comes with a fantastic collection of tools that make managing monorepos much easier. A monorepo is a multi-project and multi-library version-controlled code repository. By enabling us to reuse components and types not just between multiple front-end libraries but also between the frontend and the backend, monorepos make it simple to increase the DRYness of our code. The ability to share code across the client and server in a s∂ingle repository is a game-changer for us. There are many more advantages to monorepos, and far better papers have been written about them.

To get started with Nx you can run the following command and select the following options:

npx create-nx-workspace@latest

✔ Choose your style                     · integrated
✔ What to create in the new workspace   · angular
✔ Repository name                       · spartan
✔ Application name                      · app
✔ Default stylesheet format             · css
✔ Enable distributed caching to make your CI faster · No

Please note that all the commands are supposed to illustrate a basic setup. There’s a lot of fine tuning necessary to get the application up and running. Cloning the GitHub repository is the fastest way to get started.

Angular

The aforementioned command will create for you a Nx workspace that is already set up to be used with Angular. Well done! Your SPARTAN project's foundation has just been established!
Let me briefly explain why Angular is my preferred framework before we go on:

Angular has opinionated routing solutions, a strong HttpClient for making asynchronous web queries, and, my personal favorite, an outstanding dependency injection system. Angular provides programmers with all the resources they need to create outstanding applications right out of the box. It is more than simply a library; it is a full-fledged framework.

Also, Angular is written in TypeScript. Static type checking is now possible with our IDE, helping in identifying mistakes early on. When both the frontend and the backend are created using TypeScript, this is extremely powerful. This enables us to be typesafe from the database all the way through to the template that renders our data to the DOM!

When creating something from scratch, it's easy to overlook that applications on the internet are utilized by individuals of all abilities. It's possible that some users will need assistive technology to use our applications. Good accessibility (a11y) features have been baked into the Angular framework. By default, the Angular development team prioritizes accessibility. Look at the Angular Component Development Kit, for example. Its accessibility features are fantastic. It offers all the tools necessary to build your own extendable, aesthetically pleasing, and easily accessible components and is maintained by the framework's creators. Built with Angular, for everyone.

Building with Angular, also means building with everyone. The incredible community surrounding Angular is perhaps its best feature. They are an amazing group of folks from all different backgrounds. The amazing Angular core team, which cares about users, developers, and ensures that everyone has a say when they plan and build new features, is the community's spearhead (pardon the pun). Angular truly supports excellent community projects, and the community takes full advantage by providing tremendous tools and features on top of an amazing framework.

Analog

We are off to a strong start and have a full-fledged, complete framework as the essential component of our stack. So let's add Analog to Angular and give it some superpowers. Adding Analog to your workspace is quite simple with the brand-new Nx plugin:

Install the @analogjs/platform:

npm i @analogjs/platform

And add a preconfigured Analog application:

nx g @analogjs/platform:app analog-trpc

Analog is a metaframework for Angular. It provides you with all the benefits of Angular, but extends its capabilities with even more:

Analog uses Vite for serving and building as well as Vitest for testing. Vite is a next generation JavaScript bundler that is super fast. It also gives us access to the Vite ecosystem with hundreds of very powerful plugins. A mature frontend framework like Angular combined with access to all the benefits of Vite is truly incredible. It seems like the Angular team shares this opinion as it is also working to move the built in dev server for Angular to Vite.

// Detect dark theme var iframe = document.getElementById('tweet-1644018247748943872-879'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1644018247748943872&theme=dark" }

Another incredible advantage of Analog is that it comes equipped to handle both Server-Side Rendering (SSR) and Static Site Generation (SSG) for Angular applications. With Analog, Angular can easily power marketing websites, blog pages, and more! As Analog is SSR by default, no further configuration is necessary.
Analog comes with SSG support. It makes it simple for you to export your website as basic static assets that you can host on GitHub Pages, S3, or any other static file server! Whether you choose to go fully static or leverage the benefits of server side rendering, Analog offers all of the SSR benefits for SEO and performance today. Still, there is even more. With Angular 16, we already get non-destructive hydration and significantly improved web vitals enhancements. You can expect even greater performance once zoneless applications powered by signals are released in version 17. Building on Analog puts you in a great position to take full advantage of those features.

Last but not least, Analog supports API (server) routes and file-based routing for Angular apps. In an analog application, the folder hierarchy and filenames determine the routing. You won't ever need to declare a route array again. Don't worry, you can still use the full power of the Angular router with its route guards and resolvers by defining route metadata within your files.

TailwindCSS

Every good application needs a great UI. Although it's easier said than done, there are tools that help us do our best work. Tailwind is one of those essential tools for me.
Tailwind is "a utility-first CSS framework packed with classes like flex, pt-4, text-center and rotate-90."
These utility classes let you to modify the layout, color, spacing, font, shadows, and more to create a distinctive component design without leaving your HTML or adding any additional CSS code. To me, there are several key factors that earn Tailwind it’s place in the SPARTAN stack:

Its set of utility classes have good design principles built in.
Building your reusable UI components with tailwind gives you consistency and flexibility out of the box.
Tailwind plays together perfectly with Angular. The framework is built around components which encapsulate part of the UI and can be assembled to achieve the user experience you desire.
I would even claim that Angular makes working with tailwind especially fun: Angular’s directives are perfect to hide the often complained about ugly markup. I wrote a whole article about this directive and tailwind love affair. Also, if you dare you can something like this to extract your tw classes and keep your Angular templates clean:

// Detect dark theme var iframe = document.getElementById('tweet-1644820404861583361-882'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1644820404861583361&theme=dark" }

Warning: This seems to be highly controversial so use at your own risk...

Since we are using Vite and Nx adding tailwind will also be super straightforward. We install the necessary dependencies

npm install -D tailwindcss postcss autoprefixer

Then, we add a tailwind config to the root of our application:

const { createGlobPatternsForDependencies } = require("@nrwl/angular/tailwind");
const { join } = require("path");

/** @type {import("tailwindcss").Config} */
module.exports = {
  darkMode: 'class',
  content: ["./index.html",
    join(__dirname, "src/**/!(*.stories|*.spec).{ts,html}"),
    ...createGlobPatternsForDependencies(__dirname)
  ],
  theme: {
    extend: {}
  }
};

Finally, we tell Vite to run PostCSS and create the tailwind classes by adding a postcss.config.js file to our application:

const { join } = require('path');

module.exports = {
  plugins: {
    tailwindcss: {
      config: join(__dirname, 'tailwind.config.js')
    },
    autoprefixer: {}
  }
};

tRPC

At this point our frontend is ready to go! However, it turns out that Analog sneakily turned us into a full stack developer. Code that we put inside the server folder is actually executed on the server 🤯 It’s that easy! Well let’s take full advantage of our API being built in the same language and the same repository. Let’s make our server client interaction super smooth and super typesafe with tRPC.

tRPC stands for TypeScript Remote Procedure Call, and is a lightweight library for remotely calling backend functions on the client side. It makes communication between the backend and frontend incredibly easy taking advantage of TypeScript inference to automatically warn you of errors on your client before you even save the change on your server file! Using tRPC will feel like using an SDK for your API's server code, giving you confidence in your endpoints.

On the server, you create a tRPC API by defining your procedures. Procedures are the composable functions used to build your backend. They're composable and can be queries, mutations, or subscriptions. Routers contain multiple procedures. Often, we use a the popular Zod validator library to ensure the input from the client has exactly the shape that our procedure expects. Finally, we always export the type of our API's tRPC router so we can use it in our frontend code.

In the SPARTAN repository I have already implemented tRPC adapters for both the client inside our Angular application and the Nitro server, which Analog provides to us by default. This makes using tRPC and Analog super easy! If you are interested in the underlying source code feel free to check out the @spartan/trpc package, which is located in the libs/trpc folder. For more information on tRPC I recommend checking out their amazing documentation site trpc.io

Prisma

Now, our front-end code is typesafe, as is our server code, and our front-end and server interaction is both very smooth and typesafe. We're just a few steps away from having complete typesafety from our database to the template generating the DOM. Prisma is the tool that will bring us there.

Prisma is a Node.js and TypeScript ORM. An ORM is an Object Relational Mapper, which is a piece of code that wraps the code required to manipulate the data, allowing you to avoid using SQL and instead interact directly with an object in the same language you're using. Hibernate is a popular ORM for Java and the Spring framework, .NET has the entity framework, and Typescript has Prisma. Prisma, however, goes beyond just a simple ORM. It has an intuitive data model, automated migrations (I can't emphasize how valuable this is), typesafety, and auto-completion!

With Prisma, you include a definition of your database schema within your code repository.
Prisma then creates a properly typed Client using this information. The Prisma client is query builder that is specific to your database schema and is aware of every one of your tables, their fields, and their relationships! With Prisma, we are literally typesafe from the database to the template.

Additionally, it creates SQL migrations automatically using the Prisma schema, monitors the execution of migrations, and offers tools for identifying and resolving conflicts and drifts between migrations and the database schema. This completely changes the game as it enables your database and all of its types to evolve alongside your application code.

We can add Prisma to our stack like this:

npm install prisma --save-dev

Then, we initialize the client with:

npx prisma init

This will create a prisma folder in our Nx workspace's root directory. Inside there is a file called schema.prisma. I added the following contents:

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model note {
  id         BigInt    @id(map: "notes_pkey") @default(autoincrement())
  created_at DateTime? @default(now()) @db.Timestamptz(6)
  note       String?
}

This will tell Prisma to create a JavaScript/TypeScript client, connect to a Postgres SQL database using the DATABASE_URL connection url with a schema that has a simple table called note for our example. Of course, you will adjust the schema to fit your project.

At this point our typesafe stack is ready for development. The only thing that is missing is persistent data storage, our PostgresSQL database.

Supabase

PostgreSQL is one of the worlds most scalable databases. It is a sophisticated object-relational system applying SQL. Postgres allows you to securely store vast quantities of complex data. It enables developers to build the most sophisticated programs, carry out administrative operations, and establish integral environments. It is an open source technology trusted by millions of developers.

It turns out that every Supabase project is powered by a dedicated PostgreSQL database. Supabase is a fantastic open source Firebase replacement that is powered by the aforementioned Postgres database. It also provides a lot more features as your project expands and becomes more involved. Supabase provides solutions for common needs like as authentication, instant APIs, edge functions, real-time subscriptions, and storage, making it a robust platform on which to develop your application.

Even better, Supabase is open source at heart. You can look through the source code. You may self-host it, utilize their free plan to get started, or commit to one of their premium subscriptions to receive a fully managed production quality environment that scales with your needs.

Supabase just wrapped up their Launch Week 7 with a ton of incredible features. This includes an AI assistant that was added to their premium platform. It is aware of your database design and can help you when creating more complex SQL queries. I'm even more thrilled by their most recent releases of outstanding open source projects, such as the PostgreSQL package manager database.dev. dbdev serves the same purpose for PostgreSQL that npm does for JavaScript. It gives your PostgresSQL database incredibly easy access to packages that give your DB superpowers like full-text search or one-time-only-read data access à la Snapchat. The best thing is that dbdev can load any PostgreSQL instance that has the required fundamental extensions, independent of the Supabase platform. Again, the code is open source. I can't wait to see where this project goes in the future, and I have no doubt that we will soon be able to utilize a lot more fantastic libraries. Like Brandon Roberts puts it:

// Detect dark theme var iframe = document.getElementById('tweet-1645436665677193217-318'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1645436665677193217&theme=dark" }

Let's complete this last step and finish our typesafe, fullstack SPARTAN stack:

We will set up our persistent data storage and then use Prisma to sync our database schema to the Postgres database that our project will run on. There are two ways to get up and running with Supabase:

Connecting directly to your managed instance on supabase.com
Locally using Docker

Option 1: Connecting to supabase.com instance

This way is super easy! Simply by creating your account, you will also have set up your first project.
This means that you are ready to connect to your projects database already!

Let's connect our application to our Supabase Postgres instance:

Add a .env file at the root of your Nx workspace and add the following code snippet

# Environment variables declared in this file are automatically made available to Prisma.
# See the documentation for more detail: https://pris.ly/d/prisma-schema#accessing-environment-variables-from-the-schema

# Prisma supports the native connection string format for PostgreSQL, MySQL, SQLite, SQL Server, MongoDB and CockroachDB.
# See the documentation for all the connection string options: https://pris.ly/d/connection-strings

DATABASE_URL="postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-SUPABASE-REFERENCE-ID].supabase.co:5432/postgres?schema=public"

It's really this easy!! Prisma can now take over the DB management and make sure that our schema is migrated to our Supabase instance.

Option 2: Connecting to local supabase instance

Supabase also allows you to run a version of their system locally!

To get up and running you can follow this guide! They do a great job explaining how to get started and there is plenty of resources to help you if you get stuck.

If you want the quick and dirty way and are on a Mac. Here is what I did to get up and running:

Install supabase CLI

brew install supabase/tap/supabase

Log into CLI

supabase login

Create your access token from https://app.supabase.com/account/tokens and paste it into your terminal window.

Create Supabase project

# if you are in the spartan directory move UP!!!
cd ..
# create your project folder
mkdir spartan-supabase

# move into the new folder
cd spartan-supabase

# start a new git repository — important, don't skip this step
git init

Start Supabase services

supabase init

and

supabase start

Important: Make sure Docker is running and configured correctly!

I had Docker already installed and running. However, my setup is not compatible with the config Supabase expects by
default.
I ran the following command to get it to work for now:

DOCKER_HOST=unix:///Users/[YOUR_USER_ACCOUNT_NAME]/.docker/run/docker.sock supabase start

For more info see this issue on GitHub.

Connect to local DB

The previous step can take a while as all the docker images have to be downloaded first.
However, once everything completes you will see a console output that looks like this:

Started supabase local development setup.

         API URL: http://localhost:54321
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
        anon key: eyJh......
service_role key: eyJh......

Take your cyber-security hat off for a minute (we are working locally after all) and copy the connection string:

postgresql://postgres:postgres@localhost:54322/postgres

Add a .env file at the root of your Nx workspace and add the connection string like so:

# Environment variables declared in this file are automatically made available to Prisma.
# See the documentation for more detail: https://pris.ly/d/prisma-schema#accessing-environment-variables-from-the-schema

# Prisma supports the native connection string format for PostgreSQL, MySQL, SQLite, SQL Server, MongoDB and CockroachDB.
# See the documentation for all the connection string options: https://pris.ly/d/connection-strings

DATABASE_URL="postgresql://postgres:postgres@localhost:54322/postgres?schema=public"

Perfect! You should be able to connect to your local Supabase Postgres instance now!

Initializing the DB

Now that we have successfully set up our DB we need to set up our database schema.
Primsa makes this super easy!!

We can push the schema defined in our schema.prisma file to our DB running

yarn prisma db push

Finally, we create our prisma client by running

yarn prisma generate

That's it! Now our DB should be all set up and ready to go!

Bringing it all together

While the instructions should get you pretty close to running your own SPARTAN application, the easiest way to get started with the full stack is to clone/fork the repository. It has all the little tweaks needed to get things running done already. You can start making changes right away:

git clone https://github.com/goetzrobin/spartan.git

The files that will be most interesting to you are:
index.page.ts inside the analog-trpc application:

import { Component, OnInit } from '@angular/core';
import { injectTRPCClient } from '../../trpc-client';
import { AsyncPipe, DatePipe, JsonPipe, NgFor, NgIf } from '@angular/common';
import { FormsModule, NgForm } from '@angular/forms';
import { note } from '@prisma/client';
import { waitFor } from '../../wait-for';

const inputTw = 'focus-visible:ring-2 focus-visible:ring-red-500 focus-visible:outline-0 block w-full appearance-none rounded-lg px-3 py-2 transition-colors text-base leading-tight md:text-sm bg-black/[.05] dark:bg-zinc-50/10 focus:bg-white dark:focus:bg-dark placeholder:text-zinc-500 dark:placeholder:text-zinc-400 contrast-more:border contrast-more:border-current';
const btnTw = 'focus-visible:ring-2 focus-visible:ring-zinc-50 focus-visible:outline-0 flex items-center justify-center rounded-lg px-2 py-1.5 text-sm font-bold tracking-tight shadow-xl shadow-red-500/20 bg-[#DD0031] hover:bg-opacity-70 text-zinc-800 hover:text-primary-darker';

@Component({
  selector: 'analog-trpc-home',
  standalone: true,
  imports: [AsyncPipe, FormsModule, NgFor, DatePipe, NgIf, JsonPipe],
  host: {
    class: 'block h-full p-4'
  },
  template: `
    <div class='justify-center flex mt-20 mb-8 items-center'>
      <h1 class='font-medium italic text-6xl text-[#DD0031] font-bold'>SPARTAN</h1>
      <img class='ml-2 block w-32' alt='Spartan Logo' src='/assets/spartan.svg' />
    </div>
    <form class='py-2 flex items-center' #f='ngForm' (ngSubmit)='addPost(f)'>
      <input required autocomplete='off' class='${inputTw}' name='newTitle' [(ngModel)]='newTitle' />
      <button class='ml-2 ${btnTw}'>+
      </button>
    </form>
    <div class='mt-4'>
      <div class='mb-4 p-4 font-normal border border-zinc-500/40 rounded-md'
           *ngFor='let note of notes ?? []; trackBy: noteTrackBy'>
        <div class='flex items-center justify-between'>
          <p class='text-sm text-zinc-400'>{{note.created_at | date}}</p>
          <button class='!text-xs h-6 !bg-opacity-10 hover:!bg-opacity-50 !text-zinc-50 ${btnTw}'
                  (click)='removePost(note.id)'>x
          </button>
        </div>
        <p class='mb-4'>{{ note.note }}</p>
      </div>

      <div class='text-center rounded-xl p-20 bg-zinc-950/40' *ngIf='!loadingPosts && notes.length === 0'>
        <h3 class='text-xl font-medium'>No notes yet!</h3>
        <p class='text-zinc-400'>Add a new one and see them appear here...</p>
      </div>
    </div>
  `
})
export default class HomeComponent implements OnInit {
  private _trpc = injectTRPCClient();
  public loadingPosts = false;
  public notes: note[] = [];
  public newTitle = '';

  public ngOnInit() {
    waitFor(this._trpc.note.list.query().then(notes => this.notes = notes));
  }

  public noteTrackBy = (index: number, note: note) => {
    return note.id;
  };

  public addPost(form: NgForm) {
    if (!form.valid) {
      form.form.markAllAsTouched();
      return;
    }
    this._trpc.note.create.mutate({ title: this.newTitle }).then(() => this.fetchPosts());
    this.newTitle = '';
    form.form.reset();
  }

  public removePost(id: bigint) {
    this._trpc.note.remove.mutate({ id }).then(() => this.fetchPosts());
  }

  private fetchPosts() {
    this.loadingPosts = true;
    this._trpc.note.list.query().then(notes => {
      this.loadingPosts = false;
      this.notes = notes;
    });
  }
}

It shows you how to query, update and delete records in our DB using the tRPC client.

The client interacts with a trpc endpoint defined in the [trpc].ts file inside the server/routes/trpc folder of the same analog-trpc application:

import { appRouter } from '../../trpc/routers';
import { createContext } from '../../trpc/context';
import { createTrpcNitroHandler } from '@spartan/trpc';
// export API handler
export default createTrpcNitroHandler({
  router: appRouter,
  createContext
});

The appRouter comes from server/trpc/routers/index.ts and consolidates all other routers of your application. In our case that is the notesRouter that is in the notes file of the same folder. I suggest you should make changes to the source code of that file, e.g. remove the list procedure, and see how typescript immediately notifies you of the breaking change in the index.page.ts

import { z } from 'zod';
import { router, publicProcedure } from '../trpc';

import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()

export const noteRouter = router({
  create: publicProcedure
    .input(
      z.object({
        title: z.string(),
      }),
    ).mutation(({ input }) => prisma.note.create({data: {
      note: input.title
      }})),
  list: publicProcedure.query( () =>   prisma.note.findMany()
  ),
  remove: publicProcedure
  .input(z.object({
    id: z.bigint()
  })).mutation(({input}) => prisma.note.delete({
      where: {
        id: input.id
      }
    }))
});

This is it! You now have the full power of fullstack typesafety right at your finger tips! This is SPARTAN!

What's next

Allowing NestJs as a backend provider is one of the most frequently requested features for Analog. Nest is a powerful framework for building efficient, scalable Node.js server-side applications. It provides an application architecture which allows us to create highly testable, scalable, loosely coupled, and easily maintainable applications. The architecture is heavily inspired by Angular, which in theory makes it a perfect fit for Analog and SPARTAN.

Feature: Use NestJS integration as SSR/http server #317

brandonroberts posted on Apr 03, 2023

Which scope/s are relevant/related to the feature request?

platform

Information

NestJS is very popular Node.js framework for building APIs and is widely used in the Angular ecosystem. This feature would allow NestJS to be used as the server for the /api routes, and provided integration as the backend for SSR.

Links:

In development, NestJS would be configured under the /api path. During the build it would host the Analog application and provide additional configured API routes.

Describe any alternatives/workarounds you're currently using

No response

I would be willing to submit a PR to fix this issue

[ ] Yes
[ ] No

View on GitHub

Unfortunately, tRPC and NestJs do not play well together by default, and the tRPC team does not intend to integrate the two through an official plugin for the time being.

However, there is other tools out there that offer a similar type-safe experience built for REST-API's, which is where NestJs shines. Specifically, I am talking about ts-rest, which has an official NestJs integration. I am excited to explore those other options and see how SPARTAN can be the best possible starter for your enterprise full stack Angular projects.

With signals landing in Angular 16, I also plan to make them an integral part of the SPARTAN stack. @timdeschryver has created an amazing form library called ng-signal-forms that is completely driven by signals and already provides an absolutely amazing developer experience dealing with even the more complex scenarios we need to tackle in our real world applications. My goal is to integrate it into the current application to show how signals will transform Angular development in the future.

Finally, there is an amazing repository called Taxonomy, which serves as a great resource to the NextJs community showing off how a real world application can be built with version 13 of the framework. In an ideal world, the SPARTAN repository could become such a beautifully crafted resource for the Angular community. That is the ambitious goal I have for SPARTAN and if this article got you excited about what is possible, I invite you to reach out with your ideas and even consider contributing yourself!

The future is bright

With Analog, Angular finally has it's own meta-framework that enables us to built on top of all the amazing features that Angular provides, which gives us access to an amazing Vite ecosystem, and will enable all of us to build better, faster, and more amazing full stack Angular applications.

Together with a powerful tools like TailwindCSS, tRPC, databases like Postgres, and infrastructure providers like Supabase, who are open source at heart, I couldn't be more excited for more and more people and companies to go all in on Analog (and maybe even the SPARTAN stack) in the future.

As always, do you have any further questions or suggestions for blog posts? What do you think of this project? Is this something you could see yourself working with? I am curious to hear your thoughts. Please don't hesitate to leave a comment or send me a message.

Finally, if you liked this article feel free to like and share it with others. If you enjoy my content follow me on Twitter or Github.

Angular & signals. Everything you need to know.

Robin Goetz — Thu, 02 Mar 2023 21:47:10 +0000

On February 15th, the Angular team opened the first PR that introduces signals to the framework. This early PR has gained huge momentum and sent the Angular community in a frenzy. Everyone is talking about signals, everyone is posting about signals, everyone is prototyping with signals.

The Angular team is doing an excellent job of pushing and explaining this new reactive primitive. They are making sure that developers have access to the tools they need to grasp this novel idea that will fundamentally alter how Angular apps function in the future. In their official Github conversation, they are diligently responding to questions and address community concerns. On twitter, they are providing the public with incredible bits of information. On live broadcasts, they engage in in-depth, hour-long technical discussions with signal thought leaders. They are doing everything they can to share their enthusiasm for and knowledge about this amazing new addition to the framework.

The only thing I have been missing so far is a compilation of all of this incredible information: One resource that digests all the materials available into a coherent story. A single article that teaches me what signals are, how they fit into the Angular story, what problems they address for the framework, and what it all means for me as an Angular developer ultimately using them to build my applications.

This article is my attempt to create such a resource.

Signals. A short introduction

So what are signals? A good starting point is to look at how Solid, a relatively new and increasingly popular framework that is built around signals describes them. Especially, the Angular team worked closely with its creator and CEO of Signals Ryan Carniato to develop Angular's version of them:

Signals are the cornerstone of reactivity in Solid. They contain values that change over time; when you change a signal's value, it automatically updates anything that uses it.

That seems pretty straight forward. A signal is a wrapper around a simple value that registers what depends on that value and notifies those dependents whenever its value changes.

A comparison often used to describe them to people familiar with RxJs are BehaviorSubjects, except for the need to manually subscribe/unsubscribe.

Signals always have a value, signals are side effect free, and signals are reactive, keeping their dependents in sync.

All together they deliver one simple model of how things change in Angular applications. Something that does not quite exist today. Let's take a look by what I mean by that.

It all started (about) 10 years ago

Angular's journey towards signals started 10 years ago. This might seem like a weird statement. We are talking about signals. THE framework that inspired the Angular team SolidJs (v1.0.0) was not released until June 28th, 2021. How could Angular's journey towards signals have started 10 years ago?

Well, that is about when v1.0.0 of Angular was released (13th of June 2012,) and with it an abundance of design choices. Design choices that each came with their own set of tradeoffs and (often significant) implications on developer and user experience.

These design choices were made based on the then current technology and the information available at that time. After 10 years of advancement in browser technology (there were no arrow functions until ES6 was finalized in 2015, async functions were added with ES8 in 2017), and hundreds of thousands of real world applications running on Angular, the Angular team decided to review those design decisions and see how they played out. As always with technology (and life in general) it turns out that some decisions turned out better than others.

Clearly, one of the best decisions was to build Angular on top of Typescript. What seems like an obvious choice now, was by no means one back in 2012. Typescript was just gaining popularity, many frontend developers never had to bother with type safety before and it seemed to unnecessarily slow things down. Angular became the first major framework to be built on top of Typescript. Today we know that type safety incredibly increases confidence and velocity in building applications at scale. But let's not get too sidetracked here.

Another decision was that the view state can not only live but also be mutated anywhere in the application. It does not matter if it is a simple boolean value in your component or an item of a list nested deeply in an object of a global service. Angular will detect the changes and update the DOM accordingly.

This gives developers incredible freedom to structure our applications in ways that make sense to us, and extract more complicated logic into services, all with minimal effort and concern about how our new data gets rendered in the DOM. No matter where we put and change our state, Angular's automatic global change detection will figure out the changes and the value will magically update in the DOM.

The challenges of automatic change detection

ZoneJs and when to check for changes

Unfortunately, in reality, it is not as easy as that. Those magic updates come at a price.

To enable its automatic change detection Angular depends on ZoneJs. ZoneJs is a library that patches native browser APIs and notifies the framework whenever a significant event occurs. This leads us to the first trade-off. Before anything can happen in an Angular application ZoneJs needs to load and run, which means that Angular sort of comes with a built-in performance deficit compared to frameworks that take a different approach to synchronize model changes and the DOM.

You might also be wondering what those significant events are that I mentioned above. The list includes event listeners, setTimeouts, Promises, and more. It turns out that to keep state that is mutable anywhere in sync with the DOM pretty much any browser event is significant. This means that often, even if we do not intend to even update the DOM, Angular will need to check the complete component tree and see if any of our data bindings' values are to be updated.

So on the one side of the story, Angular tends to overcheck and do unnecessary work trying to detect changes to the model. On the other side, the algorithm that determines which bindings changed comes with significant implications.

Unidirectional data flow or ExpressionChangedAfterItHasBeenCheckedError

We learned that there is an abundance of events that trigger Angular's change detection mechanism. To ensure that applications stay performant even with a great number of components in the DOM, the underlying mechanism must be incredibly efficient.

To ensure that, Angular's change detection runs in DOM order, and checks every binding between the model and the DOM only once. Again, after years and millions of lines of Angular it becomes clear that this way of checking for changes has its downsides.

The most important is that you cannot update any of your parents' data after it has

@Component({
  selector: 'app-child',
  standalone: true,
  imports: [CommonModule],
  template: `
    <h1>Hello</h1>
  `,
})
export class ChildComponent implements OnChanges {
  @Input()
  public changed = false;

  private parent = inject(ParentComponent);

  public ngOnChanges() {
    if (this.changed) {
      this.parent.text = 'from child';
    }
  }
}

@Component({
  selector: 'my-app',
  standalone: true,
  imports: [ChildComponent],
  template: `
  {{text}}
    <app-child [changed]='true'/>
  `,
})
export class ParentComponent {
  text = 'from parent';
}

This results in the famous ExpressionChangedAfterItHasBeenCheckedError:

ERROR
Error: NG0100: ExpressionChangedAfterItHasBeenCheckedError: Expression has changed after it was checked. Previous value: 'from parent'. Current value: 'from child'. Find more at https://angular.io/errors/NG0100

Check out the Stackblitz to see the code in action.

Within a single change detection cycle we decided to go against the natural flow of the operation and update the parent after Angular has already checked its value.

You might say that this example seems a little artificial, but there are plenty of examples where the logical data flow of an application does not fit into the top-to-bottom nature of Angular's change detection. Even within Angular itself, we find this exact problem.

In the framework's FormsModule code, the validity of a parent is driven by the child. To avoid the ExpressionChangedAfterItHasBeenCheckedError when updating the parent's status. The operation had to be wrapped by an immediately resolved promise. This schedules a micro task with our update to the parents, which on completion triggers another change detection cycle, which can finally check the component tree in the allowed order and update the DOM.

I hope you are still following me.

Of course, there are techniques, like using a promise, that works around change detection's current limitations. However, they seem a little hacky and more importantly need a deep understanding of how change detection with ZoneJs works. In reality, Angular's global, automatic change detection does not always "just work."

OnPush, RxJs & why it doesn't solve all our (diamond) problems

If you are not familiar with OnPush change detection and/or want a refresher on how RxJs is commonly used, please view this super informative video by Joshua Morony that touches both on OnPush and RxJs and their importance for Angular development.

OnPush & async pipe. Performance improvement by addressing symptoms, not solving the root cause.

As mentioned above, Angular triggers change detection many times and while this is not an issue for simple applications, performance becomes a much more important topic once the amount of components and data bindings in the DOM increases.

One common way to improve performance in an Angular application is to use the OnPush change detection strategy and let Angular handle subscription management using the AsyncPipe.

The OnPush change detection strategy excludes the component marked as OnPush and all its children from the default change detection mechanism. There is a great article written by Angular University, which goes deeper into the mechanism. I highly recommend reading it.

Again, OnPush changes the way Angular detects changes for the component marked as onPush AND all its children.

The docs clearly state that:
Use the CheckOnce strategy, meaning that automatic change detection is deactivated until reactivated by setting the strategy to Default (CheckAlways). Change detection can still be explicitly invoked. This strategy applies to all child directives and cannot be overridden.

The implications of this are huge. If one of your components high up in the tree is OnPush, all other components will have to support OnPush also. This means that UI library authors have to build their library OnPush compatible because if your components do not support OnPush change detection you cannot guarantee that everyone in the Angular ecosystem can use your components.

RxJs. Powerful, declarative, and reactive programming with asynchronous streams

RxJS is a library for reactive programming using Observables, to make it easier to compose asynchronous or callback-based code.

Mike Pearson describes its incredible power perfectly in this tweet:

// Detect dark theme var iframe = document.getElementById('tweet-1618219357255106560-861'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1618219357255106560&theme=dark" }

RxJs allows us to compose declarative, reactive pipelines using Observables that clearly show in the code what series of actions and mutations will happen in an asynchronous flow. It avoids race conditions and ultimately makes your code more readable and easier to reason about.

Angular introduced many of us to RxJs. It uses in many parts of the frameworks. Most famously in the HttpClient, which exposes the response of an HTTP-call through an Observable. Also, every Angular FormControl has a property called valueChanges. Which is a multicasting observable that emits an event every time the value of the control changes, in the UI or programmatically.

Combined with OnPush and Angular's AsyncPipe, a utility that binds our Observable directly to the template, these reactive pipelines have become a major pattern to build performant, race-condition-free, declarative Angular applications.

Streams are not behaviors. Why RxJs is not the solution.

However, if you take a closer look at how Angular uses Observables you notice a pattern. Angular uses RxJs for events, more specifically to expose streams of events. These event streams do not have a current value. Alex Rickabaugh gives a great way of thinking about this in their conversation with Ryan Carniato.

He is talking about click events specifically.

You cannot ask what is the current click event. That question does not make sense. You might ask: What is the most recent click event? However, this is a fundamentally different question. Behaviors (and Angular's signals fall into this definition of behaviors) always have a value. You will always be able to ask: What is this behavior's (signal's) current value? That is the most fundamental shortcoming of RxJs streams (Observables) as a solution to the challenges the Angular team is trying to address with their new reactive primitive.

In the same conversation, they do acknowledge that RxJs's BehaviorSubject is the closest thing the library offers to a signal. It always has a value. It can notify subscribers of changes to that value, and it exposes a way to get the current value and set a new value. However, it is not integrated into RxJs very well. As soon as pipe it through an operator (e.g. map()), it becomes an Observable and loses the connection that it was a BehaviorSubject that always has a current value. Also, RxJs has a plethora of powerful operators that can be used to map, join, debounce, etc. streams. For beginners, this power comes with a very steep learning curve. The Angular team needed something more focused to build their reactive primitive.

Picking the right tool for your (diamond) problems

Also, let's remind ourselves what the team set out to do in the first place. They want to introduce a reactive primitive that they can integrate with Angular's templating engine to notify the framework when the value bound to the view changes and needs to be updated in the DOM.

One of the major goals of such a primitive is glitch-free execution. Glitch-free execution means never allowing user code to see an intermediate state where only some reactive elements have been updated (by the time you run a reactive element, every source should be updated.)
Credit for this definition goes to Milo's awesome article on fine-grained reactive performance.

Again, RxJs only offers a solution that feels hacky at best. Let's look at the example below:

@Component({
  selector: 'normal',
  standalone: true,
  imports: [CommonModule],
  template: `
    <p>Hello from {{fullName$ | async}}!</p>
    <p>{{fullNameCounter}}</p>

    <button (click)="changeName()">Change Name</button>
  `,
})
export class NormalComponent {
  public firstName = new BehaviorSubject('Peter');
  public lastName = new BehaviorSubject('Parker');

  public fullNameCounter = 0;

  public fullName$ = combineLatest([this.firstName, this.lastName]).pipe(
    tap(() => {
      this.fullNameCounter++;
    }),
    map(([firstName, lastName]) => `${firstName} ${lastName}`)
  );

  public changeName() {
    this.firstName.next('Spider');
    this.lastName.next('Man');
  }
}

We declare two BehaviorSubjects for firstName and lastName.
We combine them into an observable fullName$ that simply concatenates the two.
We declare a fullNameCounter which we increment every time our fullName$ Observable emits.
We add a changeName function that we can trigger to set firstName and lastName to a different value AT THE SAME TIME.

Our component initially displays the following

Hello from Peter Parker!

1

Once you click on the button the UI is updated to:

Hello from Spider Man!

3

This means that our fullName$ observable actually emitted twice. One time for each change to firstName and lastName. While it happened so fast that we could not see it, this component actually rendered a intermediate state just to be instantly replaced by the final, correct state.

To avoid this and achieve our goal of glitch free execution, we need to add a debounceTime to our fullName$ to avoid the duplicate execution and end up with glitch-free execution.

@Component({
  selector: 'debounced',
  standalone: true,
  imports: [CommonModule],
  template: `
    <p>Hello from {{fullName$ | async}}!</p>
    <p>{{fullNameCounter}}</p>

    <button (click)="changeName()">Change Name</button>
  `,
})
export class DebouncedComponent {
  public firstName = new BehaviorSubject('Peter');
  public lastName = new BehaviorSubject('Parker');

  public fullNameCounter = 0;

  public fullName$ = combineLatest([this.firstName, this.lastName]).pipe(
    debounceTime(0),
    tap(() => {
      this.fullNameCounter++;
    }),
    map(([firstName, lastName]) => `${firstName} ${lastName}`)
  );

  public changeName() {
    this.firstName.next('Debounced Spider');
    this.lastName.next('Man');
  }
}

Now we see the counter only increasing by one at a time, indicating that we indeed will not render an intermediate state.

Hello from Peter Parker!

1

Once you click on the button the UI is updated to:

Hello from Debounced Spider Man!

2

Again, I encourage you to check out the working example.

An important take away is that combineLatest emitting once for every change to one of the observables it combines would also would also apply if Angular decided to make @Input()s observables. While this is of the most requested features of the community, you see that it comes with additional complexity.

So what does the exact same functionality look like with a signal primitive? I am glad you asked.

@Component({
  selector: 'my-app',
  standalone: true,
  template: `
    <p>{{ fullName() }}</p>
    <p>{{signalCounter}}</p>
    <button (click)="changeName()">Increase</button>
  `,
})
export class App {
  firstName = signal('Peter');
  lastName = signal('Parker');

  signalCounter = 0;

  fullName = computed(() => {
    this.signalCounter++;
    console.log('signal name change');
    return `${this.firstName()} ${this.lastName()}`;
  });

  changeName() {
    this.firstName.set('Signal Spider');
    this.lastName.set('Man');
  }
}

Isn't the signal version's code so much easier and so much more straight forward.

Did you notice that even when you spam the changeName button, the count never goes over two?

Hello from Signal Spider Man!

2

We will go into more detail on this later, but signals only notify consumers of their changes if their value changes. To get the same functionality in RxJs we would have to add yet another operator to our Observable: distinctUnitlChanged.

It is important to note that this does not mean that RxJs time is over. That it's on its way out of Angular and not useful anymore. RxJs shines by letting developers declare asynchronous, reactive streams. You can listen to an input's change events, debounce its values, switch them to parameters for an HTTP call, and map the response to the exact model that you need in the view, all in one place. This is simply not possible with signals.

All this boils down to one thing: While both are reactive by nature, RxJs and signals solve different issues. They are complementing each other, they are not substitutes for each other. Together, they will allow for much more powerful and straightforward Angular applications.

This Article by Mike Pearson goes into much more detail about the short comings of RxJs as a reactive primitive for Angular. It helped me immensely to understand why exactly RxJs & Observable inputs are not the solution Angular needs.

A new reactive primitive: signals

Now that we understand the issues the Angular team identified, and clarified why RxJs is not the solution to those challenges, we can move on and introduce the star of today's article: signals.

Let's revisit Solid's definition of a signal that we quickly introduced at the beginning of this article:

Signals are the cornerstone of reactivity in Solid. They contain values that change over time; when you change a signal's value, it automatically updates anything that uses it.

We will take a closer look at how signals achieve this later, but let's first focus on the API currently provided by the Angular team. Most of this is copied directly from the README provided here. It is an excellent resource and definitely worth the time spent reading it 1,2,3 times:

Angular Signals are zero-argument functions (() => T). When executed, they return the current value of the signal. Executing signals does not trigger side effects, though it may lazily recompute intermediate values (lazy memoization).

Particular contexts (such as template expressions) can be reactive. In such contexts, executing a signal will return the value, but also register the signal as a dependency of the context in question. The context's owner will then be notified if any of its signal dependencies produces a new value (usually, this results in the re-execution of those expressions to consume the new values).

Note: This is what makes signals so powerful as a mechanism of change detection and DOM synchronization. The affected template is directly notified. No walking of component trees and guessing when to re-check everything is necessary!

This context and getter function mechanism allows for signal dependencies of a context to be tracked automatically and implicitly. Users do not need to declare arrays of dependencies, nor does the set of dependencies of a particular context need to remain static across executions.

Note: Compare this to combineLatest and having to add each observable to the dependency array before being able to access their values later.

Settable signals: signal()

The signal() function produces a specific type of signal known as a SettableSignal. In addition to being a getter function, SettableSignals have an additional API for changing the value of the signal (along with notifying any dependents of the change). These include the .set operation for replacing the signal value, .update for deriving a new value, and .mutate for performing internal mutation of the current value. These are exposed as functions on the signal getter itself.

const counter = signal(0);

counter.set(2);
counter.update(count => count + 1);

The signal value can be also updated in-place, using the dedicated .mutate method:

const todoList = signal<Todo[]>([]);

todoList.mutate(list => {
    list.push({title: 'One more task', completed: false});
});

Note: We do not need immutability for signals to correctly notify their dependents of changes!!

Equality

The signal creation function one can, optionally, specify an equality comparator function. The comparator is used to decide whether the new supplied value is the same, or different, as compared to the current signal’s value.

If the equality function determines that 2 values are equal it will:

block update of signal’s value;
skip change propagation.

Declarative derived values: computed()

computed() creates a memoizing signal, which calculates its value from the values of some number of input signals.

const counter = signal(0);

// Automatically updates when `counter` changes:
const isEven = computed(() => counter() % 2 === 0);

Because the calculation function used to create the computed is executed in a reactive context, any signals read by that calculation will be tracked as dependencies, and the value of the computed signal recalculated whenever any of those dependencies changes.

Similarly to signals, the computed can (optionally) specify an equality comparator function.

Side effects: effect()

effect() schedules and runs a side-effectful function inside a reactive context. Signal dependencies of this function are captured, and the side effect is re-executed whenever any of its dependencies produces a new value.

const counter = signal(0);
effect(() => console.log('The counter is:', counter()));
// The counter is: 0

counter.set(1);
// The counter is: 1

Effects do not execute synchronously with the set (see the section on glitch-free execution below), but are scheduled and resolved by the framework. The exact timing of effects is unspecified.

Note: This might sound scary at first. As developers, unspecified behavior is always the enemy. However, in this case, this gives Angular the freedom to decide when exactly an effect is executed and it can use this to optimize performance for example.

Non reactive: untracked()

Note: This is currently not part of the official README. I do want to add this here to give you a complete overview of the API.

This prevents the wrapping computation from tracking any reads of the untracked signal. This means that even if the signal changes, the context is not notified of its change.

const counter0 = signal(0);
const counter1 = signal(0);

// Executes when `counter0` changes, not when `counter1` changes:
effect(() => console.log(counter0(), untracked(counter1));

counter0.set(1);
// logs 1 0
counter1.set(1);
// does not log
counter1.set(2);
// does not log
counter1.set(3);
// does not log
counter0.set(2);
// logs 2 3

However, whenever the context is executed it will use the latest value of the untracked signal.

This is the current version of the API. Again, I want to encourage you to take the time to read the README on Github. It is absolutely phenomenal and an invaluable resource for everyone.

So how do signals work?

Again, I will mostly quote the awesome explanations of the README.

Producers and Consumers

Signals internally depend on two abstractions, Producer and Consumer. They are interfaces implemented by various parts of the reactivity system.

Producer represents values which can deliver change notifications, such as the various flavors of Signals.
Consumer represents a reactive context which may depend on some number of Producers.

In other words, Producers produce reactivity, and Consumers consume it.

Some concepts are both Producers and Consumers. For example, derived computed expressions consume other signals to produce new reactive values.

Both Producer and Consumer keep track of dependency Edges to each other. Producers are aware of which Consumers depend on their value, while Consumers are aware of all of the Producers on which they depend. These references are always bidirectional.

Together, they build a dependency graph that clearly lays out how the different nodes are related to each other.

How changes propagate through the dependency graph

We have already seen how RxJs Observables struggle to provide us with glitch free execution. We have also seen that signals elegantly solve this challenge.

Let's explore how they do that:

Push/Pull Algorithm

Angular Signals guarantees glitch-free execution by separating updates to the Producer/Consumer graph into two phases:

The first phase is performed eagerly when a Producer value is changed. This change notification is propagated through the graph, notifying Consumers which depend on the Producer of the potential update.

Crucially, during this first phase, no side effects are run, and no recomputation of intermediate or derived values is performed, only invalidation of cached values.

Once this change propagation has completed (synchronously), the second phase can begin. In this second phase, signal values may be read by the application or framework, triggering recomputation of any needed derived values which were previously invalidated.

We refer to this as the "push/pull" algorithm: "dirtiness" is eagerly pushed through the graph when a source signal is changed, but recalculation is performed lazily, only when values are pulled by reading their signals.

valueVersioning

This is probably the most complicated part of signals. First, we will take a look at the explanation provided by the Angular team. Then, we will take a look at an example.

Producers track a monotonically increasing valueVersion, representing the semantic identity of their value. The valueVersion is incremented when the Producer produces a semantically new value. The current valueVersion is saved into the dependency Edge structure when a Consumer reads from the Producer.

Before Consumers trigger their reactive operations (e.g. the side effect function for effects, or the recomputation for computeds), they poll their dependencies and ask for valueVersion to be refreshed if needed. For a computed, this will trigger recomputation of the value and the subsequent equality check, if the value is stale (which makes this polling a recursive process as the computed is also a Consumer which will poll its own Producers). If this recomputation produces a semantically changed value, valueVersion is incremented.

The Consumer can then compare the valueVersion of the new value with the one cached in its dependency Edge, to determine if that particular dependency really did change. By doing this for all Producers, the Consumer can determine that, if all valueVersions match, that no actual change to any dependency has occurred, and it can skip reacting to that change (e.g. skip running the side effect function).

Let's look at an example to better understand what is going on.

Let's assume we have the following code:

const counter = signal(0);
const isEven = computed(() => counter() % 2 === 0);
effect(() => console.log(isEven() ? 'even!' : 'odd!');

counter.set(1);
// logs odd!
counter.set(2);
// this is the change we are going to look at

This is what happens:

The change to our SettableSignal sets off our push/pull algorithm.
Our Producer counter pushes down its dirtiness and notifies its consumer isEven that its value is stale.
isEven is also a Producer, which means that it also notifies its Consumers. In this case our console.log effect. This completes the push phase.
effect now polls for isEven's current value. 5.isEven again polls for the newest version of counter. 6.counter has updated its value and valueVersion notifying isEven of its new state.
isEven recomputes its own value, determines that its value changed, and increments its value version
Finally, effect recognizes the new version value. Pulls the new value that changed to true, executes with the new value, and logs 'even!' to the console.

So let's look at what happens when we set the counter value to 4.

counter.set(4);

This is what happens:

Again, the change to our SettableSignal to 4 sets off our push/pull algorithm.
Our Producer counter pushes down its dirtiness and notifies its consumer isEven that its value is stale.
isEven is also a Producer, which means that it also notifies its Consumers. In this case our console.log effect. This completes the push phase.
effect now polls for isEven's current value.
isEven again polls for the newest version of counter.
counter has updated its value to 4 and its valueVersion 3 notifying isEven of its new state.
isEven recomputes its own value, determines in fact its value did not change. Therefore, it keeps its value version the same.
Finally, effect recognizes that isEven's valueVersion did not change. And it does not need to execute.

With the eager pushing of dirtiness down the dependency graph and the lazy pulling of values Consumer depend on signals to achieve exactly what we want: glitch-free execution.

A similar mechanism is used to track if the dependencies of a Producer went out of scope and can be garbage collected.
This means that you will never have to worry about unsubscribing from a signal. Memory leaks can simply not occur due to this way of dependency tracking!

Fine grained reactivity = fine grained change detection = performance explosion

With its own reactive primitive Angular has first class integration and can leverage all the benefits this new reactive way of doing things brings for change detection.

I think of rendering the template as an effect. Almost something like this:

const counter = signal(0);
const doubleCounter = computed(() => counter() * 2);

effect(() => renderTemplate(`
  <div>My counter is: ${counter()}</div>
  <div>My double counter is ${doubleCounter()}</div>
`));

We render the template in an effect, which becomes a consumer of each signal used in the template. These signals used will notify us when they change and we will know exactly when to re-render our template.

To better understand how incredibly efficient fine-grained reactivity and signals are when it comes to keeping the DOM and model in sync becomes clear when we compare the current change detection mechanism and the new signal-enabled mechanism.

Before we start. This is what every symbol means in the following diagrams

How Angular currently detects changes

Assume we have an application that has multiple components. Some of them have models that logically depend on each other. Others do not. Their views are all connected through parent/child relationships within the DOM tree.

Angular creates a similar tree with its top-down dirty checking change detection algorithm. Regardless of how the data of components depend on each other, the framework creates parent/child relationships between the different components.

Then, for every change detection cycle, it walks down the tree one time and compares the bindings' old value with the new value of the model. Every single binding will be checked exactly one time.

We see that a model has changed inside our component tree, symbolized by the orange circle. The model itself has no logical dependency on any other component. As we enter a new change detection cycle the following happens:

Angular starts at the top of the tree and begins to check that node
It then continues to walk along the tree to determine which components need to be updated
Finally, it reaches the component in which the model has changed.
The equality check fails and the DOM is updated.

These steps happen every time change detection is triggered.

Let's see how signal-based change detection works.

Signal powered change detection

We have the same application with multiple components. Some models logically depend on each other, while others do not. Their views are all connected through parent/child relationships within the DOM tree.

With signals, there is no need to create a tree that enables change detection. The signals used in the template notify it of their changes. That's why in this abstraction the change detection arrow is directly connected to the DOM node.

So what happens when the model changes?

The template is notified of this change and the DOM updates.

That's it.

Mind blown

No more top-down walking of a graph.

No more unnecessary comparisons.

The notification mechanism that informs the framework when to update the view is built into signals.

One can only imagine the performance improvements that come from this fine grained reactivity.

signals + RxJs = <3

I hope at this point you are just as excited for signals as I am!

I want to end this article by reiterating that signals and RxJs complement each other.

Many of the applications built with OnPush, RxJs, and the async pipe are already set up to take complete advantage of the performance increase provided by signals. The async pipe will be replaced by a signal. OnPush will completely disappear as signals notify the framework whenever a DOM update is necessary. RxJs will shine by focusing on what it does best: Modeling complex, asynchronous streams in a declarative way.

Together they will power the Angular applications of the future.

Ready. Set. Go.

It truly is an exciting time in the Angular community. I am 1000% convinced that signals will significantly improve developer and user experience of Angular applications. They provide one simple model to update Angular's views. They are performant, reactive, and will soon be an indispensable part of Angular.

I hope you are now equipped with the knowledge to take full advantage of signals when they land later this year.

As always, do you have any further questions or suggestions for blog posts? Are you excited about signals or do you still see issues the team needs to address? I am curious to hear your thoughts. Please don't hesitate to leave a comment or send me a message.

Finally, if you liked this article feel free to like and share it with others. If you enjoy my content follow me on Twitter or Github.

Dark mode with Analog & Tailwind

Robin Goetz — Fri, 17 Feb 2023 15:58:03 +0000

I entirely rebuilt my personal website with Analog and Tailwind a few weeks ago. I tweeted about it and received lot of positive feedback.
// Detect dark theme var iframe = document.getElementById('tweet-1624087896088096770-652'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1624087896088096770&theme=dark" }

One of the questions I received was about how I implemented the dark mode experience. Specifically, how does the website recognize the user's preferred color scheme while also allowing her to manually adjust the theme and remember her selection for the next time you visit the page?

I decided to publish a brief post outlining the approach I used so that others may implement a comparable user experience. In this post, we will build the following dark mode mechanism:

We identify the color scheme picked by the user and change our theme accordingly.
A button will allow the user to change the current theme and toggle between dark and light mode.
The current theme should be saved (I'll do this with localStorage), so that the right theme is used the next time the user accesses the page.

Note

Analog, Vite, and Tailwind are used in this tutorial. When building dark mode for standard Angular projects that use Webpack, the same concepts apply. Tailwind makes enabling dark mode a breeze. Again, the same functionality may be implemented with normal CSS or style processors such as SCSS.

What is AnalogJS

Analog is a full-stack meta-framework for building applications and websites with Angular. It is similar to other meta-frameworks such as Next.JS, Nuxt, or SvelteKit but built on top of Angular. It's features include:

Vite/Vitest/Playwright
File-based routing
Support for API/server routes
Hybrid SSR/SSG support
Supports Angular CLI/Nx workspaces

and more.

Getting started with Analog

The easiest way to get started is to use the Open Stackblitz button on the analogjs.org website.

If you want to develop locally you can use the following command:

npm create analog@latest

This will scaffold a basic Analog application. Once all dependencies are installed you can start your development server with:

npm run start

Now that we have a vanilla Analog project up and running we can start implementing the dark mode functionality.

Adding Tailwind to Analog

The great news is that Analog & Vite support PostCSS out of the box. So we can mostly just follow Tailwind's Using PostCSS installation guide.

Fist we install our dependencies

npm install -D tailwindcss postcss autoprefixer

Then in our root directory we create two files:

1. postcss.config.js

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

This file tells Vite to enable PostCSS and run the tailwindcss and autoprefixer plugins.

2. tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{html,ts}'],
  darkMode: 'class',
  theme: {
    extend: {},
  },
  plugins: [],
};

This file ensures that all Tailwind classes in the source folder are picked up.
Two small changes to this file compared to the Tailwind guide:

For the content property we change the file ending to ts.
We add the darkMode property and set its value to class. These changes ensure that our Angular files are picked up and allow us to manually toggle Tailwind's dark mode classes by adding or removing the dark class from the html element.

3. Add default styles to styles.css

Finally, we need to add the Tailwind directives to our main css file.

/*
  Allow percentage-based heights in the application
*/
html,
body {
  height: 100%;
}
/*
  Remove built-in form typography styles
*/
input,
button,
textarea,
select {
  font: inherit;
}
/*
  Avoid text overflows
*/
p,
h1,
h2,
h3,
h4,
h5,
h6 {
  overflow-wrap: break-word;
}
/*
  Create a root stacking context
*/
app-root {
  isolation: isolate;
}

@tailwind base;
@tailwind components;
@tailwind utilities;

As you noticed, I also added some other awesome css resets inspired by a great Jon Comeau blog post.

Adding initialization script to index.html

After setting up Tailwind, we can move on to the initial stage of incorporating dark mode onto our page.

In order to get started, we first add a <script> element to our index.html file. This blocking script makes sure that the appropriate theme value is saved in localStorage and that the dark class is immediately applied to the <html> element as soon as the user loads the page.

All this occurs before our Angular application takes control and, more importantly, before any content is painted. This allows the browser to immediately apply the appropriate dark Tailwind classes when painting our user interface.

For more information, check out this part of another outstanding Jon Comeau blog post that describes this technique in detail.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>MyApp</title>
    <base href="/" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/x-icon" href="/src/favicon.ico" />
    <link rel="stylesheet" href="/src/styles.css" />
    <script>
      if (
        // check if user had saved dark as their 
        // theme when accessing page before
        localStorage.theme === 'dark' ||
        // or user's requesting dark color 
        // scheme through operating system
        (!('theme' in localStorage) &&
          window.matchMedia('(prefers-color-scheme: dark)').matches)
      ) {
        // then if we have access to the document and the element
        // we add the dark class to the html element and
        // store the dark value in the localStorage
        if (document && document.documentElement) {
          document.documentElement.classList.add('dark');
          localStorage.setItem('theme', 'dark');
        }
      } else {
        // else if we have access to the document and the element
        // we remove the dark class to the html element and 
        // store the value light in the localStorage
        if (document && document.documentElement) {
          document.documentElement.classList.remove('dark');
          localStorage.setItem('theme', 'light');
        }
      }
    </script>
  </head>
  <body>
    <app-root></app-root>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Let's take a closer look at what is happening inside our script tag:

if (
        // check if user had saved dark as their 
        // theme when accessing page before
        localStorage.theme === 'dark' ||
        // or user's requesting dark color 
        // scheme through operating system
        (!('theme' in localStorage) &&
          window.matchMedia('(prefers-color-scheme: dark)').matches)
      ) {
        // then if we have access to the document and the element
        // we add the dark class to the html element and
        // store the dark value in the localStorage
        if (document && document.documentElement) {
          document.documentElement.classList.add('dark');
          localStorage.setItem('theme', 'dark');
        }
      } else {
        // else if we have access to the document and the element
        // we remove the dark class to the html element and 
        // store the value light in the localStorage
        if (document && document.documentElement) {
          document.documentElement.classList.remove('dark');
          localStorage.setItem('theme', 'light');
        }
      }

We check if there is already a dark value set to the theme property of the user's localStorage OR if the user is requesting a dark theme using the operating system.
If that is the case and we have access to the document and its html element, we add the dark class to that element and store the dark value for our theme in the localStorage.
If that is NOT the case we and we have access to the document and its html element, we remove the dark class from that element and store the light value for our theme in the localStorage.

Check out the source code for this file here.

At this point we have a page that supports Tailwind and initially renders the correct color scheme.

Creating the ThemeService

Let's move on and allow our visitors to manually toggle their preferred theme.
To do this we will create a singleton Angular service that will do 5 things:

It will sync with localStorage when the application first loads.
It will keep track of theme changes in memory.
It will exposes a method to toggle the theme and write those theme changes back to localStorage.
It will add/remove the dark class from the html element as necessary.
It will expose the current theme as an Observable for other parts of the application.

Let's create a new Angular service in the following location: /src/libs/theme/theme.service.ts. We add the following code:

@Injectable({
  providedIn: 'root',
})
export class ThemeService implements OnDestroy {
  // A. Setting up our dependencies
  // A.1 since we will access localStorage with AnalogJS
  // (which can be used for server side rendering)
  // we will use the PLATFORM_ID to see if we are executing in the browser and
  // it is available
  private _platformId = inject(PLATFORM_ID);
  // A.2 we use Angular's renderer to add/remove the dark class from the html element
  private _renderer = inject(RendererFactory2).createRenderer(null, null);
  // A.3 we use Angular's DOCUMENT injection token to avoid directly accessing the document object
  private _document = inject(DOCUMENT);

  // B. Initializing our in memory theme store
  // B.1 we want to give every subscriber the current value of our theme
  // even if they subscribe after the first value was emitted
  private _theme$ = new ReplaySubject<'light' | 'dark'>(1);
  // B.2 we expose the current theme so our app can access it and e.g. show
  // a different icon for the button to toggle it
  public theme$ = this._theme$.asObservable();
  // B.3 this emits when the service is destroyed and used to clean up subscriptions
  private _destroyed$ = new Subject<void>();

  // C. Sync and listen to theme changes on service creation
  constructor() {
    // we check the current value in the localStorage to see what theme was set
    // by the code in the index.html file and load that into our _theme$ replaysubject
    this.syncThemeFromLocalStorage();
    // we also immediately subscribe to our theme$ variable and add/remove
    // the dark class from the html element
    this.toggleClassOnThemeChanges();
  }

  // C.1 sync with the theme set in the localStorage by our index.html script tag
  private syncThemeFromLocalStorage(): void {
    // if we are in the browser we know we have access to localstorage
    if (isPlatformBrowser(this._platformId)) {
      // we load the appropriate value from the localStorage into our _theme$ replaysubject
      this._theme$.next(
        localStorage.getItem('theme') === 'dark' ? 'dark' : 'light'
      );
    }
  }
  // C.2 Subscribe to theme changes until the service is destroyed
  // and add/remove class from html element
  private toggleClassOnThemeChanges(): void {
    // until our service is destroyed we subscribe to all changes in the theme$ variable
    this.theme$.pipe(takeUntil(this._destroyed$)).subscribe((theme) => {
      // if it is dark we add the dark class to the html element
      if (theme === 'dark') {
        this._renderer.addClass(this._document.documentElement, 'dark');
      } else {
        // else if is added already, we remove it
        if (this._document.documentElement.className.includes('dark')) {
          this._renderer.removeClass(this._document.documentElement, 'dark');
        }
      }
    });
  }

  // D. Expose a public function that allows us to change the theme from anywhere in our application
  public toggleDarkMode(): void {
    const newTheme =
      localStorage.getItem('theme') === 'dark' ? 'light' : 'dark';
    localStorage.setItem('theme', newTheme);
    this._theme$.next(newTheme);
  }

  // E. Clean up our subscriptions when the service gets destroyed
  public ngOnDestroy(): void {
    this._destroyed$.next();
    this._destroyed$.complete();
  }
}

Let's break down what is happening here:

A. First we set up our dependencies
A.1 We will need to access localStorage. Analog can be used for server side rendering. Therefore, we are not guaranteed that our code will only be run in the browser. Therefore, we inject the PLATFORM_ID so we can check if we are executing in the browser and localStorage is available.
A.2 We inject Angular's RendererFactory and pass in null as the arguments when executing the createRenderer function. This will give us the default renderer. We will use this renderer to add/remove the dark class from our document's html element.
A.3 We get access to the document using Angular's DOCUMENT injection token. Again, Analog can be used with Server Side Rendering. Therefore, we must avoid directly accessing the browser's document object.

B. We continue with initializing our in memory theme store
B.1 We use a ReplaySubject with buffer size 1 to share the theme value (which can be light or dark.) The ReplaySubject ensures that the last value is provided to any subscriber even if they subscribe after the latest value was emitted.
B.2 Outside our service we expose the current theme as a simple Observable.
B.3 Finally, we set up a _destroyed$ Subject, which we use to unsubscribe from all our Observables when our service is destroyed.

Now that everything is set up let's see what happens when the service is created.

C. When the service is constructed we sync our theme from the localStorage. Then, we subscribe to our theme$ changes and add/remove the dark class from our html element accordingly.
C.1 The appropriate theme has already been saved in the localStorage by the <script> in our index.html file has already stored the correct theme in the localStorage. We just pull that value from localStorage. To achieve that, we first determine whether we are in the browser and hence have access to localStorage. If we are, we load the stored value into our _theme$ ReplaySubject.
C.2 Still in the constructor we subscribe to theme$ changes until our service is _destroyed$. If the theme is dark we add the dark class to the _document's html element using Angular's _renderer. If the theme is light and the dark class already exists on the html element, then we simply remove it.

D. Then we expose a public function, which toggles our theme based on the current value in the localStorage. The new theme is subsequently pushed as the next value into of _theme$ ReplaySubject. This ensures that our _theme$ and localStorage are always in sync.

E. Lastly, we configure the mechanism to terminate our subscriptions when our service gets destroyed. Our service is a singleton provided in root. It would only be destroyed if the entire application was. Therefore, we should be fine even if we don't unsubscribe here, but it's always a good idea to clean up your subscriptions.

The live code for our service can be found here.

Important Note: All import paths must be the same for Angular to construct a singleton service. Therefore, we can not import our ThemeService using relative paths. We add the following to vite.config.js in order to support Vite's use of absolute import paths:

export default defineConfig(({ mode }) => ({
...
  resolve: {
    ...
    alias: {
      src: path.resolve(__dirname, './src'),
    },
  },
...
}));

As a result, we are able to import everything from the src directory. For instance, in our (home).ts route, we will now import the service with
import { ThemeService } from 'src/libs/theme/theme.service';
rather than
import { ThemeService } from '../../libs/theme/theme.service';. This is because using relative paths can cause Angular to create multiple service instances, which can have very strange and unexpected effects.

Yes, I spent way too much time trying to figure out why my ThemeService was showing different themes in different components...

Using our ThemeService in our Analog app

Now that our service is set up, let's use it in our Analog application. We will add a button to the header that allows us to toggle the theme from anywhere in the app. We also display the theme in our HomeComponent to illustrate that the current theme can be accessed from anywhere in our application. We also add Tailwind classes that support both light and dark theme styling.

Adding a button to the AppComponent

Let's add the following to our /src/app/app.component.ts:

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [AsyncPipe, RouterOutlet],
  host: {
    class:
      'block h-full bg-zinc-50 text-zinc-900 dark:text-zinc-50 dark:bg-zinc-900',
  },
  template: ` 
  <header class="p-4">
  <button (click)="toggleTheme()">Toggle theme</button>
  </header>
  <router-outlet></router-outlet> `,
})
export class AppComponent {
  private _themeService = inject(ThemeService);

  public toggleTheme(): void {
    this._themeService.toggleDarkMode();
  }
}

The code for the component is here.

This will be the entry point to our Analog application.

The user can toggle the theme by clicking a button that is displayed in the template's header.

To make our application look super sleek, we also added Tailwind classes to the host. These include classes that start with the prefix dark, which are used when the dark class is added to the site's html element. The following classes instruct Tailwind to use a super-light zinc-gray background and a super-dark zinc-gray text-color by default and to invert them when dark is present:

bg-zinc-50 text-zinc-900 dark:text-zinc-50 dark:bg-zinc-900

Inside the component we hooked up its toggleTheme method with the ThemeService's toggleDarkMode method. The service is simply injected to the component using Angular's inject function.

Displaying the current theme on Analog's (home)page

Finally, let's display the current theme on our homepage.

Using the Angular Router as a foundation, Analog offers filesystem-based routing. It provides us with a simple method for organizing our application's folders and filenames to create our route tree. To find out more about the supported types of routes, I strongly recommend checking out Analog's routing documentation.

We will keep it simple for our purposes and simply create an index route by creating the following component at /src/app/routes/(home).ts:

@Component({
  selector: 'app-home',
  standalone: true,
  imports: [AsyncPipe],
  host: {
    class: 'block'
  },
  template: `
  <div class="flex p-12 gap-8 items-center justify-center">
  <img class="h-20 w-20" src="/analog.svg"/>
  <div class='w-[1px] h-14 dark:bg-zinc-50 bg-zinc-900'></div>
  <img class="h-20 w-20" src="/tailwind.svg"/>
  </div>
  <h2 class="text-2xl text-center">Analog + Tailwind: Darkmode</h2>
  <p class="mt-2 text-center">Current theme: {{theme$ | async}}</p>
  `,
})
export default class HomeComponent {
  private _themeService = inject(ThemeService);
  public theme$ = this._themeService.theme$;
}

The code for the HomeComponent is here.

Again, we add some Tailwind magic, including some dark classes. Additionally, we inject our ThemeService into the component and expose it's theme$ observable, which we simply display in our template using Angular's AsyncPipe.

Since we set up our application to import our service via import { ThemeService } from 'src/libs/theme/theme.service'; instead of a relative path, we will see that our theme$ value will correctly display light if we are using our light theme and dark if we decide to toggle to our dark theme.

Check out the complete example here!

Wrapping Up

Awesome! We have now implemented dark mode in our Analog app. Our implementation respects the user's preferred color scheme by default. It avoids flashing of the wrong theme, and allows us to access and toggle the theme from anywhere in our application!

Do you have any further questions or suggestions for blog posts? Have you tried Analog before? Do you know what meta-frameworks are and how we can benefit from them? I want to hear your ideas. Please don't hesitate to leave a comment or send me a message.

Finally, if you liked this article feel free to like and share it with others. If you enjoy my content follow me on Twitter or Github.

Mastering Angular Structural Directives - Micro-syntax in the wild

Robin Goetz — Sun, 12 Feb 2023 16:00:00 +0000

We covered every aspect of micro-syntax in the previous article. We gained a much better understanding of what Angular does when we use structural directives by examining the various parts of the official syntax reference. To reinforce this knowledge, this article will look closely at Angular's built-in NgIf and NgFor directives.

*ngIf - Micro-syntax to ng-template

Let's start with a very common use case that most of you have probably seen in some form or another.

In our template, we want to show some asynchronous data that we are fetching from an API.
We want to show a loading indicator while we wait for the data.

Following best practices, we do not manually subscribe in our component, but instead move that logic into the template. Allowing Angular's AsyncPipe to handle the heavy lifting.

We will write something like this:

Let's go through the same process of identifying the various parts of this statement and looking at how Angular will translate them.

We apply the same color code:

We have the asterisk * and the ngIf selector on the left side.
Then there's the right side. It is composed of three parts:

an :expression
an :as declaration
a :keyExp declaration

Let's take a closer look at each one:

Because the right side begins with an expression, we know that this expression will be assigned to a '@Input()' with the same name as the selector (ngIf).
When Angular translates our micro-syntax, it becomes:

<ng-template [ngIf]="(items$ | async)">...

Let's continue.

Next, we see that we export our expression into a local variable for use in our template. While this is not explicitly stated in the documentation, it is entirely possible. The mechanism enabling this is similar to the a :keyExp declaration mechanism.
To make 'items' hold the correct value, we must add the ngIf key to our context with the value of our @Input() ngIf. The reason for this becomes clear when we translate our micro-syntax into the ng-template version:

<ng-template
[ngIf]="(items$ | async)"
let-items="ngIf"
>...

For an:as declaration, Angular uses the name of the @Input() variable as the :export or context' key assigned to the local variable that can be used in the template. Because the @Input() in our case is ngIf, ngIf must be a key in the context, and before rendering our template, we must assign our @Input ngIf to our context' ngIf key.

Finally, we have a regular :keyExp declaration that assigns the loading TemplateRef to a @Input() of the NgIf directive. We use our camelCase-fusing logic to determine that our input must be named ngIfElse.
When we translate this part of our micro-syntax into the ng-template version, we get:

<ng-template
...
[ngIfElse]="loading"
>...

Putting it all together we end up with the following:

This allows us to infer a lot of information about how the NgIf directive. Let's make some predictions about the source code and see if they hold up.

We know that the NgIf directive has:

an @Input() called ngIf
a context object with an ngIf key
another @Input() called ngIfElse

Let's check out the official NgIf source code and see if we are correct:

  /**
   * The Boolean expression to evaluate as the condition for showing a template.
   */
  @Input()
  set ngIf(condition: T) {
    this._context.$implicit = this._context.ngIf = condition;
    this._updateView();
  }

  private _updateView() {
    if (this._context.$implicit) {
          ...
          this._thenViewRef = this._viewContainer.createEmbeddedView(this._thenTemplateRef , this._context);
    } else {
          ...
          this._elseViewRef = this._viewContainer.createEmbeddedView(this._elseTemplateRef, this._context);
    }
  }

We see the @Input() ngIf. Whenever the condition passed is set, the NgIf context's implicit and ngIf keys are assigned our condition. Then the view is updated. When the condition passed in is truthy, the our template is rendered, else we render the _elseTemplateRef.

  /**
   * A template to show if the condition expression evaluates to false.
   */
  @Input()
  set ngIfElse(templateRef: TemplateRef<NgIfContext<T>>|null) {
    assertTemplate('ngIfElse', templateRef);
    this._elseTemplateRef = templateRef;
    this._elseViewRef = null;  // clear previous view if any.
    this._updateView();
  }

This template comes from our @Input ngIfElse, which makes sure it is a valid template and assigns it to our _elseTemplateRef.

/**
 * @publicApi
 */
export class NgIfContext<T = unknown> {
  public $implicit: T = null!;
  public ngIf: T = null!;
}

Finally, we can confirm that our context indeed has an ngIf key, next to the $implicit. Both are assigned to our truthy expression passed in through the @Input() ngIf. That's why we can extract our async items$ using a :let declaration using the micro syntax:

*ngIf="(items$ | async); let items; else: template"

Or using a let-declaration using the ng-template and our $implicit key:

<ng-template
  [ngIf]="(items$ | async)"
  let-items>
  {{items | json}}
</ng-template>

We will get the exact same results!

To see examples of everything check out this Stackblitz!

*ngFor - Micro-syntax to ng-template, reloaded.

Let's move on to the NgFor directive. We assume another familiar scenario similar to the one for NgIf.

We want to display a list of some asynchronous data that we are fetching from an API in our template.
Once we receive the list, we want to display every item of the list using a custom template.

Our code will look like this:

Again, we color, divide, and conquer:

The asterisk * and the ngFor selector make up the left side.
The right side is made up out of 3 parts:

an :let declaration
a :keyExp declaration
an :as declaration

Let's take a closer look at each one:

While the colon is frequently left out for a cleaner reading of the NgFor micro-syntax, this is actually a classic :keyExp. We assign our (items$ | async) expression to our directive's camelCase-fused @Input() ngForOf. This input value is also assigned to the context' ngForOf key, allowing us to use an :as expression to access it. We can then use our local items variable in the template directly.
When translated to the ng-template version, this section becomes:

<ng-template
  [ngForOf]="(items$ | async)"
  let-items="ngForOf"
>...

Last but not least, we have a simple :as declaration extracting the index key of our context into the i variable:

<ng-template
  let-i="index"
>...

Putting everything together we end up with this:

Again, we can use the info above to make some predictions about the source code and see if they hold up.

We know that the NgFor directive has:

an @Input() called ngForOf taking in an iterable, for which each item one template gets rendered
a context object with an $implicit key making the current to-be-rendered item accessible.
a context object with an ngForOf key to expose the value above
a context object with an index key making the current to-be-rendered index accessible.

Let's check out the official NgIf source code and see if we are correct:

  @Input()
  set ngForOf(ngForOf: U&NgIterable<T>|undefined|null) {
    this._ngForOf = ngForOf;
    this._ngForOfDirty = true;
  }

Again, we see in the source code the @Input() ngForOf taking in our iterable. In addition, a flag is used to indicate that this variable is dirty. This is done because NgFor does not simply render and re-render every item in our iterable every time. It actually performs some advanced calculations to determine whether a template needs to be re-rendered in order to ensure that the NgFor directive performs well even with larger lists and more complex templates.

If you want to learn more about NgFor, I recommend you look at its source code. We'll proceed to look at the context object.

/**
 * @publicApi
 */
export class NgForOfContext<T, U extends NgIterable<T> = NgIterable<T>> {
  constructor(public $implicit: T, public ngForOf: U, public index: number, public count: number) {}

  get first(): boolean {
    return this.index === 0;
  }

  get last(): boolean {
    return this.index === this.count - 1;
  }

  get even(): boolean {
    return this.index % 2 === 0;
  }

  get odd(): boolean {
    return !this.even;
  }
}

Again, we find our $implicit, ngForOf, and index keys. You can also see that there is a bunch of other keys available for you to access in your template!
If you are interested in seeing NgFor and it's context in action. Check out this StackBlitz!

What's next?

I can't tell you how proud I am of you if you've made it this far! I hope you now have a clearer understanding of how Angular works its magic on structural directive micro-syntax. Undoubtedly, this subject is among the most challenging aspects of the Angular framework. I hoped that by breaking things down into smaller, more manageable chunks, I would be able to provide you with the knowledge and tools you need to both better comprehend the built-in structural directives and make your own custom structural directives.

Let us pause for a moment (or two, or three) to digest all of this new information and celebrate that the asterisk has returned.

We will improve our custom "*exchangeRate" directive in the following (and possibly final?) article of this series so that it can work with the micro-syntax with ease. Additionally, instead of re-rendering the template after each successful API call, we will expose the response as an observable to our template.

Do you have any further queries or subjects you'd like me to discuss? Do you believe a video on structural directives would be beneficial? I'm interested in hearing your ideas. If you have any suggestions for future posts, please do leave a comment or send me a message.

Finally, if you liked this article feel free to like and share it with others. If you enjoy my content follow me on Twitter or Github.

Mastering Angular Structural Directives - Micro-syntax demystified

Robin Goetz — Fri, 10 Feb 2023 19:52:38 +0000

In the previous article of this series, we took a closer look at the context object and how we can use it to expose all kinds of data and even functions to our template. Combined with @Input()s and dependency injection, we got a first glimpse of how powerful structural directives are once they can interact with the rest of our application or even the outside world (using Angular's HttpClient.)

While I quickly "introduced" the structural directive micro-syntax in the first article, we have applied all our custom directives directly to ng-templates. Now it is time to reintroduce the asterisk and take the time to understand how Angular interprets this shorthand syntax.

One structural directive per element

Before we begin exploring the ins and outs of Angular's micro-syntax, I should note that we can only ever apply one structural directive per host element. As the official documentation states: The reason is simplicity. Structural directives can do complex things with the host element and its descendants. When two directives lay claim to the same host element, which one should take precedence?
Therefore, if we add multiple structural directives to the same element the Angular compiler will throw an error.

Understanding the syntax reference

I spent a lot of time trying to figure out the best way to introduce Angular's micro syntax.
Should I do it the same way I picked up structural directives. I got gradually introduced to more and more bits, pieces, and gotcha's as I used structural directives. However, I always lacked a deeper, more complete understanding of the underlying mechanisms that make them work.
Or should I start with the official syntax reference, which is intimidating to say the least. I always found that part of the Angular documentation to be one of the most confusing. However, once I truly wrapped my head around it, it was like an epiphany and absolutely changed the way I look at and understand structural directives.

Therefore, I decided to start with that: The official syntax reference. I will do my best to break things down and explain every piece of it. Together, we will tackle it and take our Angular skills to the next level.

We got this!

Without further ado: the structural directive syntax reference

When I first saw this expression in the documentation, I had no idea any of this meant. I was overwhelmed to be completely honest. But equipped with the knowledge from our previous articles, some clever coloring, and breaking this monstrosity down into smaller pieces, we will demystify this syntax and understand what is going on.

Adding colors makes the distinct parts more obvious.

Much better! I also want to flip the first :let and :expression. The reason will become clear a little later.

Awesome! This already looks a lot less intimidating.

Components of the structural directive syntax reference

Let's dive in and start breaking the syntax down into its sub-components.
The equal sign divides the expression into two sides:

1. *:prefix

The asterisk * and the :prefix make up the left side.
The asterisk instructs Angular to encapsulate this directive in a ng-template.
:prefix is always the directive's selector. If the directive has an input with the same name as our :prefix AND the right side starts with an :expression, it can also serve as the first input of our directive.
I will explain this in detail in the section below.

2. (:expression | :let) (';' | ',')? (:let | :as | :keyExp)*

The right side is made up of several subgroups. A logical group is denoted by a pair of blue parentheses. The blue vertical line | indicates a logical OR within a group. If the group is followed by a blue question mark ?, it is optional. If it is followed by a blue asterisk *****, the group can be repeated multiple times. (This includes 0 times.)

Again, we can divide the right side into 3 smaller parts:

1. (:expression | :let)

This first part is either an :expression or a :let declaration.

1.1 :expression

If we have an input parameter with the same name as the selector in our directive, this part must always be a :expression or Angular will throw an error.
Any valid Angular expression is regarded an :expression. This includes boolean (true/false) values, function calls, and component variables.

The following example demonstrates how the micro-syntax binds the :expression to the :prefix input of the component:

@Directive({
  standalone: true,
  // our directives selector, which becomes the :prefix
  selector: '[myNgIf]',
})
export class MyNgIfDirective {
  // dependencies needed to render
  private _vcr = inject(ViewContainerRef);
  private _template = inject(TemplateRef);

  private _isRendered = false;
  @Input()
  // an input with the same name as the selector
  // binding the :expression to the :prefix (myNgIf)
  set myNgIf(expression: boolean) {
    this._isRendered = expression;
    if (this._isRendered) {
      this._vcr.createEmbeddedView(this._template);
    } else {
      this._vcr.clear();
    }
  }
}

@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule, MyNgIfDirective],
  template: `
  <button (click)="isRendering = !isRendering">Toggle</button>
  <p>We can now bind an Angular expression like our component variable isRendering ({{isRendering}}) to our myNgIf input.
  If isRendering is true we will see our component rendered below:

  <div *myNgIf="isRendering">Rendered.</div>
  `,
})
export class App {
  public isRendering = false;
}

Link to Stackblitz.

If no @Input() property matches the selector of the directive, this first part must be a :let declaration.

1.2 :let declaration

In the previous article, we saw let declarations applied directly to the ng-template. We learned how they extract the variables from our context and make them available for use in our template.

The micro-syntax :let declarations accomplish the same thing.
Their structures are very similar and look like this:

let local=“export ';'?”

local is the local variable name used in the template.
export refers to the value exported by the directive under a specific name, which is one of the keys in our context object! Except when the key is $implicit. This key is unique and is assigned to 'let local' by default. If we don't include ="export" in our let declaration, the value of $implicit is automatically assigned to our local variable.
';'? is an optional semi-colon that indicates the end of the let declaration.

An example of the micro-syntax :let declaration:

@Directive({
  standalone: true,
  selector: '[myLet]',
})
export class MyLetDirective implements OnInit {
  // dependencies needed to render
  private _vcr = inject(ViewContainerRef);
  private _template = inject(TemplateRef);

  public ngOnInit() {
    this._vcr.createEmbeddedView(this._template, {
      $implicit: { hello: 'World from implicit' },
      second: { hello: 'World from second' },
    });
  }
}
@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule, MyLetDirective],
  template: `
  <div *myLet="let ctx;">
  <p>{{ctx | json}}</p>
  </div>

  <div *myLet="let secondCtx = second">
  <p>{{secondCtx | json}}</p>
  </div>
  `,
})
export class App {}

Link to Stackblitz.

As you can see we can extract both the $implicit into the ctx template variable and the second key into the secondCtx variable using our :let declaration. Take note that we added a semi-colon at the end of the first declaration. This is not required. The second declaration without it also works.

2. (; | ,)?

We can add an optional semi-colon or comma after our initial :expression or :let declaration to separate it from the following component. This can be used to make your code more readable. It is not necessary.

Let us update our simple directive from the:let declaration example to demonstrate that we can, but are not required to, use semi-colons and commas to separate our :let declarations.

@Directive({
  standalone: true,
  selector: '[myLet]',
})
export class MyLetDirective implements OnInit {
  // dependencies needed to render
  private _vcr = inject(ViewContainerRef);
  private _template = inject(TemplateRef);

  public ngOnInit() {
    this._vcr.createEmbeddedView(this._template, {
      $implicit: { hello: 'World from implicit' },
      second: { hello: 'World from second' },
    });
  }
}

@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule, MyLetDirective],
  template: `
  <div *myLet="let context; let secondCtx = second">
  semi-colon
  <p>{{context | json}}</p>
  <p>{{secondCtx | json}}</p>
  </div>

  <div *myLet="let context, let secondCtx = second">
  colon
  <p>{{secondCtx | json}}</p>
  <p>{{secondCtx | json}}</p>
  </div>

  <div *myLet="let context let secondCtx = second">
  nothing
  <p>{{context | json}}</p>
  <p>{{secondCtx | json}}</p>
  </div>
  `,
})
export class App {}

Link to Stackblitz.

To make our code clearer, we can add a semicolon or even a comma between our :let statements. If we exclude these, our code still functions as intended.

3. (:let |:as | :keyExp)*

3.1 :let declaration

This third section may be repeated as many times as needed following the initial :expression, :let declaration, or the optional semicolon or comma. It can either be a :let, :as, or :keyExp declaration. The :let declaration is the same as the one we used above. We move on to the :as declaration.

3.2 :as declaration

Similar to the :let declaration, the :as declaration extracts context variables and binds them to the template.
It's syntax is very similar to our :let declaration.
It looks like this:

export as local ';'?

export is the value exported by the directive under a given name, aka one of the keys in our context object!
local is the local variable name used in the template.
';'? is an optional semi-colon that indicates the end of the let declaration.

One could say, that :as is pretty much :let in reverse order. Angular actually translates both expression to the same "simple" let declaration: let-local="export" on the ng-template.
We can see this in action rewriting our AppComponent to use an :as declaration instead of the second :let declaration:

@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule, MyLetDirective],
  template: `
  <div *myLet="let context; second as secondCtx">
  nothing
  <p>{{context | json}}</p>
  <p>{{secondCtx | json}}</p>
  </div>
  `,
})
export class App {}

Link to Stackblitz.

With the: as an d:let declarations, we now have two tools to extract context data for usage in our template. If a property of our directive has the same name as our selector, we also know how to assign a @Input() value to it. We frequently need to give our directive multiple inputs. See how :keyExp declarations do this.

3.3 :keyExp declaration

It's syntax is very similar to our :let declaration.
It looks like this:

key ":"? :expression (as local)? ';'?

key ":"? indicates an assignment to a special @Input() variable of our directive. Why special? The literal key value and the directive's selector, or the :prefix, are combined to form the variable's name. The key is appended to the end of the :prefix in camelCase. :prefix and key become :prefixKey, ngIf and else become ngIfElse. You can see this in the Angular source code. Also, you can see that the colon to indicate an assignment (similar to assigning a value to a key in a JavaScript object) is optional. *ngIf="loaded; else loadingTemplate" and *ngIf="loaded; else: loadingTemplate" are the same thing.
:expression is the Angular expression bound to your :prefixKey @Input()
(as local)? is an optional way to directly use the :expression, which was passed in as an @Input(), in the template with the local variable name. Very important: For this to work, the directive's context object must have a camelCase-fused-key. A directive like this: <div *calculateAvg="let avg; data: (data$ | async) as testData">...</div> Would need to have a calculateAvgTestData key in its context object for testData to expose the correct value.
';'? is an optional semi-colon that indicates the end of the let declaration.

Let's look at the full source code of the *calculateAvg example from above:

@Directive({
  // directive to calculate the average
  selector: '[calculateAvg]',
  standalone: true,
})
export class CalculateAvgDirective {
  // dependencies needed to render the template
  private _vcr = inject(ViewContainerRef);
  private _template = inject(TemplateRef);

  // our average that we calculate whenever
  // new data is provided
  private _avg = 0;

  // private reference to our data so we can calculate the
  //  average in the set function
  private _data = [];
  @Input()
  // we want to be able to use the key data in our key expression
  // we know that we need to camelCase-fuse our key with the directive name
  // calculateAvg (:prefix) + data (key) => calculateAvgData (:prefixKey)
  set calculateAvgData(values: number[]) {
    // store data passed in
    this._data = values;
    const sum = this._data.reduce((a, b) => a + b, 0);
    // calculate the average
    this._avg = sum / Math.max(1, values.length);

    // render template
    this._vcr.createEmbeddedView(this._template, {
      // make avg available through $implicit
      $implicit: this._avg,
      // make data available for as expression
      calculateAvgData: this._data,
    });
  }
}
@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule, CalculateAvgDirective],
  template: `
  <div *calculateAvg="let avg; data: (data$ | async) as testData">
  micro-syntax: {{avg}} is the average of {{testData}}
  </div>

  <ng-template 
    calculateAvg
    [calculateAvgData]="(data$ | async)"
    let-testData="calculateAvgData"
    let-avg
    >
    ng-template: {{avg}} is the average of {{testData}}
    </ng-template>

  `,
})
export class App {
  data$ = of([1, 3, 3, 1, 4, 0, 2, 2, 1, 3]);
}

I highly recommend to examine working code is here.

Don't worry if a lot of information sounds confusing or still a bit unclear. :keyExp declarations are definitely the hardest part to understand about structural directives and their micro-syntax.

What's next

Today, we've covered every aspect of micro-syntax. We dissected and thoroughly examined the official syntax reference. I hope this has helped you understand what Angular does when structural directives are used in your applications. However, I believe that in order to cement today's knowledge, we should look at how the syntax is used in Angular's built-in directives. In the following article, we will apply what we've learned today and dissect the NgIf and NgFor directives.

If you liked this article feel free to like and share it with others. If you enjoy my content follow me on Twitter or Github.

Mastering Angular Structural Directives - It’s all about the context

Robin Goetz — Sat, 21 Jan 2023 18:54:55 +0000

In the first article of this series, we learned how to render our first template to the DOM using structural directives. We saw that the asterisk micro syntax is actually optional and expanded to an ng-template by Angular. Then, we leveraged dependency injection to obtain references to our template and view container and used them to create new DOM elements.

So far we have only rendered static HTML to the DOM. There was no outside interaction between our template and the rest of the application. Let's change that and introduce structural directive's context.

Note: We will only use the ng-template notation in this post and dedicate the next post solely to understanding the asterisk micro syntax.

Structural Directive's Context - Definition & Structure

We already know how to use the ViewContainerRef's createEmbeddedView method to render our template. This function takes a second optional parameter called context. The ViewContainerRef's documentation defines it as such:
The data-binding context of the embedded view, as declared in the <ng-template> usage. Optional. Default is undefined.

It seems like we can use this context object to bind data to our template. Unfortunately, this is all the information we get directly from the ViewContainerRef documentation. We are left in the dark on how to use it or if there is a specific structure to this context object.

More about the structure is provided by the documentation of another built-in structural directive we have not mentioned yet: NgTemplateOutlet

This directive inserts an embedded view from a prepared TemplateRef and takes in a template reference and (amongst others) an additional input: context. Let’s see how context is described in this part of the documentation:

A context object to attach to the EmbeddedViewRef. This should be an object, the object's keys will be available for binding by the local template let declarations. Using the key $implicit in the context object will set its value as default

We combine the information from both docs and recap:

We can pass a context object to the ViewContainerRef's createEmbeddedView method.
This object will be used to bind data to the embedded view, which is rendered based on our ng-template.
The keys of the context object will be available for the ng-template through let declarations.
There is a special key $implicit that is used as the default value of those let declarations.

Already, things are much clearer. But what exactly are those let declarations? And how can we use them to connect our context object to our ng-template?

Let declarations - binding context to the template

Let declarations can be used on ng-template tags to give us access to the context provided by the applied structural directive.

Their structure looks like this:

let-local=“export”

local is the local variable name used in the template.
export is the value exported by the directive under a given name, aka one of the keys in our context object! Unless the key is $implicit. This key is special and is assigned to let-local by default. If =“export” is omitted in a let declaration, the value of $implicit is automatically assigned to our local variable.

Let's look at an example to better understand how this data binding works:

  // We create a directive that allows us to provide
  // the template with information on how long a
  // specific unit of measurement is in meters.
  @Directive({
    selector: '[unitsInMeters]',
  })
  export class UnitsInMetersDirective {
  // The context passed to the ng-template
  // it holds information about how long a unit is in meters
  private unitsInMetersContext = {
    // the default is meter
    $implicit: 1,
    // a mile is 1609.34 meters long
    mile: 1609.34,
  };

  // To render our template to the DOM we:
  // get the template ref from the ng-template host
  private template = inject(TemplateRef);
  // get the viewcontainerref from the host: <!--comment-->
  private vcr = inject(ViewContainerRef);

  // on initialization of our directive we
  // render our template to the DOM passing
  // our unitsInMetersContext
  public ngOnInit(): void {
    this.vcr.createEmbeddedView(this.template, this.unitsInMetersContext);
  }
}

Awesome! We can finally bind data to our templates! For now, we only used constant values, but we are in no way limited to only that.

Dynamic context - Unleashing the full power of structural directives

As we build more complex directives we will need to pass more than just constant values to our template. Angular does not limit the type of values of our context's keys. We can pass pretty much any type of value to our template.

Examples are:

Static values such as constant numbers, strings, or other objects.
Dynamic values, which are references to properties of our directive. Of course, can include @Input() properties.
Observables, which are references to observables within our directive. I realize that those are also "just" properties of our directive, but they are really powerful and can avoid excessive re-rendering of our template.
Functions, which are references to our directive's functions. It should be noted, that the this keyword used in those functions needs to be bound to the directive's execution context (a different context than the one this article is focused on). To achieve that you can either wrap the function passed in the context with an arrow function or use .bind(this) on the function.

Let's see the true power of context in practice and create a structural directive exposing information about currency exchange rates - the exchangeRate directive.

Our requirements are:

The directive should allow the user to input the from currency and the to currency. These inputs are ISO 3-Letter Currency Codes.
By default, we convert from USD to EUR
We call an API to return the current rate between the currencies
Once we get the value we render our template and expose:
1. the from currency code
2. the to currency code
3. the rate
4. the reverseFn function, which can be called to switch the from and to variables. Reversing the current rate

Using it in a component should be as easy as this:

@Component({
  selector: 'my-app',
  template: `
  <label>From <input [(ngModel)]="fromInput"> </label>
  <label>To <input [(ngModel)]="toInput"> </label>

  <ng-template exchangeRate [from]="fromInput" [to]="toInput" let-from="from" let-to="to" let-rate="rate" let-reverse="reverseFn">
  <p>Converting from {{from}} to {{to}} the exchange rate is: {{rate}}</p>
  <button (click)="reverse()">Reverse</button>
  </ng-template>
  `,
})
export class AppComponent {
  public fromInput = 'USD';
  public toInput = 'EUR';
}

Let's look at the overall structure of how our directive might implement this functionality:

@Directive({
  selector: '[exchangeRate]',
})
export class ExchangeRateDirective implements OnInit, OnChanges {
  // from input which defaults to USD if none is provided
  @Input('from')
  public from = 'USD';
  // to input which defaults to EUR if none is provided
  @Input('to')
  public to = 'EUR';

  // TemplateRef and ViewContainerRef to render to DOM
  private template = inject(TemplateRef);
  private vcr = inject(ViewContainerRef);
  // HttpClient to query API
  private http = inject(HttpClient);

  // initally we render our template with the default values
  public ngOnInit(): void {
    this.getExchangeRateFromApiCreateContextRenderTemplate();
  }

  // whenever an input value changes we query our
  // api for the new rate and re-render the template
  // given the new input is a 3 letter currency code
  public ngOnChanges(changes: SimpleChanges): void {
    // get the new from value or keep old
    const newFrom = changes.from ? changes.from.currentValue : this.from;
    // get the new to value or keep old
    const newTo = changes.to ? changes.to.currentValue : this.to;
    // over simplified check if inputs are currency code
    if (newFrom.length !== 3 || newTo.length !== 3) {
      // stop processing changes as definitely not a valid currency code
      return;
    }
    // get new rate and render template to DOM
    this.getExchangeRateFromApiCreateContextRenderTemplate();
  }

  private getExchangeRateFromApiCreateContextRenderTemplate(): void {
    ...
  }

  public reverseRate() {
    // this is for demonstration purposes only
    // since from and to are inputs reassigning those inputs
    // might be confusing to the consumer of the directive
    const oldFrom = this.from;
    this.from = this.to;
    this.to = oldFrom;
    this.getExchangeRateFromApiCreateContextRenderTemplate();
  }
}

First, we take in our from and to inputs with the defaults from the requirements. Then, we inject our dependencies which we need to render our template to the DOM and make API calls to get the newest exchange rate.

  // from input which defaults to USD if none is provided
  @Input('from')
  public from = 'USD';
  // to input which defaults to EUR if none is provided
  @Input('to')
  public to = 'EUR';

  // TemplateRef and ViewContainerRef to render to DOM
  private template = inject(TemplateRef);
  private vcr = inject(ViewContainerRef);
  // HttpClient to query API
  private http = inject(HttpClient);

On initialization, we get the exchange rate from the API, create the context and render the template.

  // initally we render our template with the default values
  public ngOnInit(): void {
    this.getExchangeRateFromApiCreateContextRenderTemplate();
  }

On every subsequent change, we determine if the inputs changed and if they are a currency code. If they did not, we do nothing. If they did, we again get the exchange rate from the API, create the context and render the template.

  // whenever an input value changes we query our
  // api for the new rate and re-render the template
  // given the new input is a 3 letter currency code
  public ngOnChanges(changes: SimpleChanges): void {
    // get the new from value or keep old
    const newFrom = changes.from ? changes.from.currentValue : this.from;
    // get the new to value or keep old
    const newTo = changes.to ? changes.to.currentValue : this.to;
    // over simplified check if inputs are currency code
    if (newFrom.length !== 3 || newTo.length !== 3) {
      // stop processing changes as definitely not a valid currency code
      return;
    }
    // get new rate and render template to DOM
    this.getExchangeRateFromApiCreateContextRenderTemplate();
  }

Finally, we define a reverse function that reverses the from and to variable, then gets the reversed rate from the API, creates the context, and renders the template.

  public reverseRate() {
    // this is for demonstration purposes only
    // since from and to are inputs reassigning those inputs
    // might be confusing to the consumer of the directive
    const oldFrom = this.from;
    this.from = this.to;
    this.to = oldFrom;
    this.getExchangeRateFromApiCreateContextRenderTemplate();
  }

Let's take a closer look at the getExchangeRateFromApiCreateContextRenderTemplate method and see how it ties everything together.

  private getExchangeRateFromApiCreateContextRenderTemplate(): void {
    // 1. we get the new rate based on the from and to currencies and re-render our template
    this.http
      .get(`https://open.er-api.com/v6/latest/${this.from}`)
      .pipe(
        // 2. we only care about the immediate response
        take(1),
        // 3. we extract the rate for the currency
        // we convert to
        map((response: ExchangeRateResponse) => {
          return response?.rates?.[this.to] ?? -1;
        })
      )
      .subscribe((rate) => {
        // 4. once the rate arrives, we build the
        // context which will be exposed to our template.
        const exchangeRateContext = {
          // 4.1 current value of our from property
          from: this.from,
          // 4.2 current value of our to property
          to: this.to,
          // 4.3 rate returned by api
          rate,
          // 4.4 function reference to refresh
          reverseFn: () => this.reverseRate(),
        };
        this.vcr.clear();
        // 5. we render the template with the new context
        this.vcr.createEmbeddedView(this.template, exchangeRateContext);
      });
  }

The method uses the HttpClient's get method to request a new rate from the API for our from currency code and returns an observable of the response.
We ensure we only react to the first value emitted using the take(1) RxJs operator.
With the map operator, the API response inside of the observable is mapped to the rate for our to currency code. If we cannot find the code, we return a symbolic value of -1. This indicates to users of our directive that something is off so they can display an appropriate message. Of course, this is oversimplified, but I hope you get the idea.
We subscribe to our observable and obtain the rate. Once the rate is received, we build our context with the following keys:
1. from: the current currency code of our directives from property.
2. to: the current currency code of our directives to property
3. rate: the exchange rate returned from the API
4. reverseFn: a reference to our directives reverseRate function bound to the current execution context with an arrow function.
We render our template to the DOM and pass the new context.

Now, we can use our directive in the AppComponent as described above:

@Component({
  selector: 'my-app',
  template: `
  <label>From <input [(ngModel)]="fromInput"> </label>
  <label>To <input [(ngModel)]="toInput"> </label>

  <ng-template exchangeRate [from]="fromInput" [to]="toInput" let-from="from" let-to="to" let-rate="rate" let-reverse="reverseFn">
  <p>Converting from {{from}} to {{to}} the exchange rate is: {{rate}}</p>
  <button (click)="reverse()">Reverse</button>
  </ng-template>
  `,
})
export class AppComponent {
  public fromInput = 'USD';
  public toInput = 'EUR';
}

And see our code in action:

Awesome! We have now interacted with the rest of the app through inputs and outputs, even the world outside our application by injecting the HttpClient and making API calls to remote servers! Everything from within our structural directive.

Check out the working directive here

One step at a time

There are a lot of ways to improve our directive such as improving performance by avoiding re-renders using observables for our exposed variables and strict type checking for our context in the ng-template.

However, these are topics for another post. If you are interested in how to strictly type your context exposed to templates Thomas Laforge wrote this great article covering everything you need to know. I highly recommend you read it!

Let's be proud of ourselves today. We took another step to master structural directives in Angular by understanding the key concept of the context. Let's take some time to digest all this new information and get ready to learn everything about the structural directive micro syntax. The magic that brings us back our asterisk.

Mastering Angular Structural Directives - The basics

Robin Goetz — Thu, 12 Jan 2023 21:14:50 +0000

Structural directives in Angular are one of the framework’s most powerful tools. We encounter them early in our Angular journeys. They are integral to developing even the most basic Angular applications.

Whether it is rendering a list of todos or toggling some icon once a todo is completed, *ngFor and *ngIf become familiar faces in the earliest days as Angular developers. From then on, they stay our trusted partners on which we frequently rely in day-to-day development tasks. However, the inner workings of these directives are often a mystery to both new and experienced developers.

In this series, we will delve deeper into the internal workings of structural directives, providing a comprehensive understanding of what is going on under the asterisk. In this article, we will examine what needs to happen for a structural directive to render to the DOM.

*easyToSpot - A minimal introduction to structural directive’s micro-syntax

You probably spotted two of the built-in structural directives: NgIf and NgFor. They were easy to identify, as I followed the convention laid out directly in the Angular docs: When structural directives are applied they generally are prefixed by an asterisk, *. More interestingly, the docs also state that Angular uses this convention to wrap the element the directive is applied to, also known as the host element, with an ng-template:

<div *ngIf="hero">{{hero.name}}</div>

becomes

<ng-template [ngIf]="hero">
  <div>{{hero.name}}</div>
</ng-template>

Looking at this longhand version, we can identify two ways of defining structural directives:

By what they do (as the official documentation does): Structural directives are directives that change the DOM layout by adding and removing DOM elements.
By what they are: Directives that are applied to ng-templates and come with an optional micro syntax that makes our HTML nicer to read.

Directive superpowers - Rendering to the DOM with the help of dependency injection

We can fully utilize Angular's dependency injection (DI). because we are dealing with a directive. Given that we know the personality of the directive's host, we can access it by simply injecting it into our directive.

The following example demonstrates this:

@Component({
  // in our app
  selector: 'app',
  // ourDirective is applied to the host component
  template: `<host ourDirective ></host>`,
})
export class AppComponent {}

@Component({
  selector: 'host',
  // the host simply renders the currentName
  template: `{{ currentName }}`,
})
export class HostComponent {
  // by default the currentName is setByTheHost
  currentName = 'setByTheHost';
}

@Directive({
  selector: '[ourDirective]',
})
export class OurDirective implements OnInit {
  // ourDirective uses DI to get access to the HostComponent
  public hostComponent = inject(HostComponent);

  public ngOnInit(): void {
    // after 3 seconds OurDirective sets the hostComponent's currentName as changedByDirective
    setTimeout(() => {
      this.hostComponent.currentName = 'changedByDirective';
    }, 3000);
  }
}

If you want to see the code in action you can check out this Stackblitz.

Injecting the template

From earlier, we know that structural directives are always applied to ng-templates. Therefore, we can inject Angular's TemplateRef, which provides us with the necessary information to render the template to the DOM. Let's look at the code below to see the internal workings of the TemplateRef:

@Component({
  selector: 'my-app',
  template: `<ng-template [ourDirective]>I am in the template</ng-template>`,
})
export class AppComponent {}

@Directive({
  selector: '[ourDirective]',
})
export class OurDirective implements OnInit {
  private template = inject(TemplateRef);

  public ngOnInit(): void {
    console.log(
      (this.template as any)._declarationTContainer.tViews.template + ''
    );
  }
}

This will log the TemplateRef's instructions, which tell Angular how to generate our DOM element to the console:

function AppComponent_ng_template_0_Template(rf, ctx) { if (rf & 1) {
i0.ɵɵtext(0, "I am in the template");
} }

Link to Stackblitz

Now that we have the information on how to render our template, we need somewhere to render it. Again, Angular's dependency injection system gives us access to what we need. The ViewContainerRef.

Injecting the view container

Every Angular component or directive has access to something called the ViewContainerRef. The official documentation defines it as a container where one or more views can be attached to a component.

We can think of it as a reference to a virtual container around an anchor element. The anchor element indicates the place in the DOM where we can dynamically create new elements. The container can instantiate new elements dynamically. It will render those new elements as siblings of the anchor element.

Our anchor element can be a custom element, an element node, or even a comment element. Let's take a look at the example below:

@Component({
  selector: 'my-app',
  template: `
  <our-component></our-component>
  <div ourDirective>On div</div>
  <ng-template ourDirective>On ng-template</ng-template>
  `,
})
export class AppComponent {}

@Directive({
  selector: '[ourDirective]',
})
export class OurDirective {
  private vcr = inject(ViewContainerRef);

  public ngOnInit(): void {
    console.log(this.vcr.element.nativeElement);
  }
}

@Component({
  selector: 'our-component',
  template: `<div>Our Component</div>`,
})
export class OurComponent {
  private vcr = inject(ViewContainerRef);

  public ngOnInit(): void {
    console.log(this.vcr.element.nativeElement);
  }
}

This produces the following results in the Stackblitz and Chrome consoles:

We see that our ViewContainerRef's native elements are our custom element, a regular HTML div element, and in the case of the ng-template, a  comment that Angular inserts into the HTML for any (potential) view it manages. Each time we get the DOM anchor which the ViewContainerRef can use to create new (sibling) elements.

Again, I encourage you to check out the working code in the Stackblitz.

Putting the two together

Finally, we have everything we need to live up to the official definition of structural directives:

Change the DOM layout by adding and removing DOM elements.

Let's create a custom structural directive that renders our template to the DOM not once, but TWO times! Super exciting!

@Directive({
  selector: '[twoTimes]',
})
export class TwoTimesDirective implements OnInit {
  // get the template ref from the ng-template host
  private template = inject(TemplateRef);
  // get the viewcontainerref from the host: <!--comment-->
  private vcr = inject(ViewContainerRef);

  // on initialization of our directive, render our template to the DOM twice
  public ngOnInit(): void {
    this.vcr.createEmbeddedView(this.template);
    this.vcr.createEmbeddedView(this.template);
  }
}

We inject both TemplateRef and ViewContainerRef into our directive. In our ngOnInit lifecycle hook, we create two sibling elements based on the template obtained from the directive's host.

@Component({
  selector: 'my-app',
  template: `
  <p *twoTimes>Two times from asterisk</p>
  <ng-template twoTimes><p>Two times from ng-template</p></ng-template>
  `,
})
export class AppComponent {}

To illustrate that our micro-syntax is correctly transpiled we use both alternatives in our AppComponent. The result is a total of four elements rendered to the DOM. Each component created two siblings to the  from the respective ViewContainerRef:

<my-app ng-version="15.0.2">
  <p>Two times from asterisk</p>
  <p>Two times from asterisk</p>
  <!--container-->

  <p>Two times from ng-template</p>
  <p>Two times from ng-template</p>
  <!--container-->
</my-app>

Link to Stackblitz

Just getting started

In this article, we took the first steps to truly understanding how structural directives work. However, we have just scratched the surface. We barely even peeked under the asterisk. To be able to truly leverage the power of structural components we will need to understand how we can pass data to our template using a context object, how we can ensure strict template type checking for said context, and how the structural directive syntax is parsed.

So let's pat ourselves on the back, take a quick NSDR (Non Sleep Deep Rest) break to let the information settle, and get excited about the next part of our journey to structural directive mastery.

Reusable Buttons with Angular, Tailwind & Storybook

Robin Goetz — Mon, 28 Nov 2022 06:30:14 +0000

What will we build?

We will build a custom Angular directive that applies our style systems button design to the element it is applied to.

Why a directive?

You get all the benefits of tailwind and its powerful styling techniques without losing the accessibility coming from the default html elements.
With a directive your styles are not tied to the button element. Other elements, like links/anchors, can also look like a button. This flexibility makes it easier for you to write great looking and accessible applications & websites.

Why Tailwind?

Its set of utility classes have good design principles built in.
Building your reusable UI components with tailwind gives you consistency and flexibility out of the box
You can use Angular’s directives and components to hide the often complained about ugly markup.

The code.

This tutorial needs an Angular project that is configured to run with Tailwind (and Storybook if you want to get the interactive demo from above).

The setup.

The easiest way to follow along is by forking my project on Github and checking out the 0-base-storybook-setup branch

You will find an NX project with an example app and a libs with a ui subdirectory, which contains the atoms directory and the storybook library.

The storybook library allows you to run the npx nx run ui-storybook:storybook (or nx run ui-storybook:storybook if you have nx installed globally) command. This generates all stories in the ui directory. It is also configured to correctly render all Tailwind classes.

The atoms directory (based on Brad Frost’s atomic design principles finally contains our button library, the entry point of today's tutorial.

Let’s see if we wired up our storybook and tailwind config correctly.

Let's get started!

We create a simple attribute directive that adds a blue background color to our button.

Create a directory named button in the src directory.

Add the button.directive.ts file in this newly created folder.

Add the following contents to the file:

import {Directive} from "@angular/core";

@Directive({
  selector: '[natButton]',
  standalone: true,
})
export class ButtonDirective {
}

Note: As you see we are using Angular’s new standalone config. If you are using Modules make sure to add your directive to the declarations and exports arrays

Next, we will use Angular’s HostBinding decorator & a private twClasses variable to bind the tailwind utility class bg-sky-500 to our host elements class attribute

import {Directive, HostBinding} from "@angular/core";

@Directive({
  selector: '[natButton]',
  standalone: true,
})
export class ButtonDirective {
  @HostBinding('class')
  private twClasses = 'bg-sky-500'
}

So far so good! Let’s add button.stories.ts in the same directory and write a simple story to see if storybook renders our new button directive correctly.

import {ButtonDirective} from "./button.directive";
import {Meta, Story} from "@storybook/angular";

export default {
  title: 'Design System/Atoms/Button',
} as Meta<ButtonDirective>;

export const Default: Story<ButtonDirective> = () => ({
  moduleMetadata: {
    imports: [ButtonDirective],
  },
  template: `<button natButton>Click</button>`
});

Awesome! You just created your first story following the Component Story Format. Let’s break down the code:

Our default export tells storybook the metadata of our stories. Following storybooks naming convention we create our Button stories in the Atoms directory of our Design System project.
We then export the Default story for our ButtonDirective. To configure the story we add the directive to the moduleMetadata array and the button element in our template.

Lets run the npx nx run ui-storybook:storybook command and see if we get our Click button with the sky blue background.

We open localhost:4400, navigate into the Atoms folder and select our Default Button Story.

Awesome! Let's take this button to the next level.

Making it real.

So far our button is not very impressive.

So let’s grab some designs from our (imaginary) designer friends and give our directive superpowers. Luckily, I prepared some good looking buttons for you here.

Copy the classes of the primary button and add them to our directive.

import {Directive, HostBinding} from "@angular/core";

@Directive({
  selector: '[natButton]',
  standalone: true,
})
export class ButtonDirective {
  @HostBinding('class')
  private twClasses = `inline-flex items-center rounded-md border border-transparent bg-sky-600 px-4 py-2 text-sm font-medium text-white shadow-sm hover:bg-sky-700 focus:outline-none focus:ring-2 focus:ring-sky-500 focus:ring-offset-2`
}

Refresh your storybook page and see how beautiful our button looks now.

Making it smart.

While our button looks great, so far we just copied around a bunch of tailwind classes.

Time to make our directive smart and support multiple themes and sizes.

First, let’s split our long twClasses string into smaller groups based on their functionality.

import {Directive, HostBinding} from "@angular/core";

const base = 'inline-flex items-center rounded-md border font-medium shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2'
const size = 'px-4 py-2 text-sm'
const theme = 'border-transparent bg-sky-600 text-white hover:bg-sky-700 focus:ring-sky-500'

@Directive({
  selector: '[natButton]',
  standalone: true,
})
export class ButtonDirective {
  @HostBinding('class')
  private twClasses = `${base} ${size} ${theme}`
}

Much better! Can you guess where we are going with this?
Let’s add an input property to our directive that lets us change the theme!

import {Directive, HostBinding, Input} from "@angular/core";

const base = 'inline-flex items-center rounded-md border font-medium shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2'
const size = 'px-4 py-2 text-sm'
const theme = 'border-transparent bg-sky-600 text-white hover:bg-sky-700 focus:ring-sky-500'
const themeSecondary = 'border-gray-300 bg-white text-gray-700 hover:bg-sky-700 focus:ring-gray-50'

export type Theme = 'primary' | 'secondary';

const buildTwClasses = (currentTheme: Theme): string =>
  `${base} ${size} ${currentTheme === 'secondary' ? themeSecondary : theme}`;

@Directive({
  selector: '[natButton]',
  standalone: true,
})
export class ButtonDirective {
  @HostBinding('class')
  private twClasses = buildTwClasses('primary')

  private _theme: Theme = 'primary';
  @Input()
  set theme(value: Theme) {
    this._theme = value;
    this.twClasses = buildTwClasses(this._theme);
  }
}

What exactly is happening in this code? 

We added the theme input to our directive which takes in a parameter of type Theme, which is our currently supported themes, primary and secondary.
There is a buildTwClasses helper function that builds the tailwind classes for our buttons based on the currentTheme we pass in.
Our set function rebuilds the twClasses every time the theme input changes and assigns it to our twClasses property, which is bound to the host's class property.

Let’s manually change our story template to use the secondary theme and see if our code works.

import {ButtonDirective} from "./button.directive";
import {Meta, Story} from "@storybook/angular";

export default {
  title: 'Design System/Atoms/Button',
} as Meta<ButtonDirective>;

export const Default: Story<ButtonDirective> = () => ({
  moduleMetadata: {
    imports: [ButtonDirective],
  },
  template: `<button natButton theme="secondary">Click</button>`
});

Refresh the page to see if the changes are picked up.

They are!! If you got this far you are now equipped with the fundamental knowledge to build beautiful buttons or links that look like buttons or anything you want that looks like buttons.

However, there are a lot of improvements and enhancements we can add. So if I sparked your interest keep on reading!

Making it super smart

So far we have a decent button directive. However, as our design system grows and designers are adding large buttons used in CTA’s of the new version of our app. They also pointed out that there is no visual hint to when a button is disabled. Let’s update our button.directive.ts and make sure we add some styles for that to our button base.

const base = `inline-flex items-center rounded-md border font-medium shadow-sm
  focus:outline-none focus:ring-2 focus:ring-offset-2
  disabled:opacity-50 disabled:focus:ring-0 disabled:active:ring-0`;

Next, we add a new input property called size to our directive.
It accepts inputs of type Size, which is our supported sizes, base and l.
While we are here let’s refactor our Tailwind configurations.

Instead of toggling between string constants, let's create objects that hold the class strings organized by the Theme and Size inputs respectively.

export const themes = ['primary', 'secondary'] as const;
export type Theme = typeof themes[number];
const themeClasses: { [key in Theme]: string } = {
  primary: 'border-transparent bg-sky-600 text-white hover:bg-sky-700 disabled:bg-sky-600 focus:ring-sky-500',
  secondary: 'border-gray-300 bg-white text-gray-700 hover:bg-gray-50 disabled:bg-white focus:ring-sky-500'
}

export const sizes = ['base', 'l'] as const;
export type Size = typeof sizes[number];
const sizeClasses: { [key in Size]: string } = {
  base: 'px-4 py-2 text-sm',
  l: 'px-5 py-3 text-base'
};

Did you notice that we create those types based on constant string arrays of our supported themes & sizes. As we add support for sizes and themes our types will magically adjust! Super smart!

In our buildTwClasses function we can now use our inputs as keys to look up the respective classes. Using this approach we can easily add new themes or sizes as our design grows.

const buildTwClasses = (currentTheme: Theme, size: Size): string =>
  `${base} ${sizeClasses[size]} ${themeClasses[currentTheme]}`;

Our directive with all its inputs on configuration now looks like this:

import {Directive, HostBinding, Input} from "@angular/core";

const base = `inline-flex items-center rounded-md border font-medium shadow-sm
  focus:outline-none focus:ring-2 focus:ring-offset-2
  disabled:opacity-50 disabled:focus:ring-0 disabled:active:ring-0`;

export const themes = ['primary', 'secondary'] as const;
export type Theme = typeof themes[number];
const themeClasses: { [key in Theme]: string } = {
  primary: 'border-transparent bg-sky-600 text-white hover:bg-sky-700 disabled:bg-sky-600 focus:ring-sky-500',
  secondary: 'border-gray-300 bg-white text-gray-700 hover:bg-gray-50 disabled:bg-white focus:ring-sky-500'
}

export const sizes = ['base', 'l'] as const;
export type Size = typeof sizes[number];
const sizeClasses: { [key in Size]: string } = {
  base: 'px-4 py-2 text-sm',
  l: 'px-5 py-3 text-base'
};

const buildTwClasses = (currentTheme: Theme, size: Size): string =>
  `${base} ${sizeClasses[size]} ${themeClasses[currentTheme]}`;

@Directive({
  selector: '[natButton]',
  standalone: true,
})
export class ButtonDirective {
  @HostBinding('class')
  private twClasses = buildTwClasses('primary', 'base');

  private _theme: Theme = 'primary';
  @Input()
  set theme(value: Theme) {
    this._theme = value;
    this.twClasses = buildTwClasses(this._theme, this._size);
  }

  private _size: Size = 'base';
  @Input()
  set size(value: Size) {
    this._size = value;
    this.twClasses = buildTwClasses(this._theme, this._size);
  }
}

Again, we can manually update our story, checking if our new size input is picked up correctly.

import {ButtonDirective} from "./button.directive";
import {Meta, Story} from "@storybook/angular";

export default {
  title: 'Design System/Atoms/Button',
} as Meta<ButtonDirective>;

export const Default: Story<ButtonDirective> = () => ({
  moduleMetadata: {
    imports: [ButtonDirective],
  },
  template: `<button natButton theme="secondary" size="l">Click</button>`
});

Perfect! A large button with our secondary theme is displayed!

Leveling up our storytelling.

Right now we are still updating our stories file a lot to preview our changes. Wouldn’t it be great to be able to see all the different button styles update dynamically in our storybook? Let’s make it happen.

In our button.stories.ts file, we create a ButtonDirectiveProps type that will drive our story controls. It extends the ButtonDirective with the content property.

type ButtonDirectiveProps = ButtonDirective & {
  content: string;
};

We then specify that we want a select control for our size & theme inputs and tell storybook to populate their options with the supported sizes & themes respectively.

export default {
  title: 'Design System/Atoms/Button',
  argTypes: {
    size: {
      control: { type: 'select' },
      options: sizes,
    },
    theme: {
      control: { type: 'select' },
      options: themes,
    },
  },
} as Meta<ButtonDirectiveProps>;

Next, we add some default args for our stories. Let’s take the first of each input options and set our content to Angular & Tailwind rock.

const DefaultArgs = {size: sizes[0], theme: themes[0], content: 'Angular & Tailwind rock'};

We then rename our Default story to Template and add the args parameter to the function. Our args will be of type ButtonDirectiveProps, which we extend with our button specific disabled property and then bind to the stories props. We update our template to bind our angular inputs to the new props we provide.
Lastly, we copy the Template as described in the Storybook introduction and set the stories arguments to our defaults, finally setting the disabled property to false.

const Template: Story<ButtonDirectiveProps & {  disabled: boolean; }> = (args) => ({
  props: args,
  moduleMetadata: {
    imports: [ButtonDirective],
  },
  template: `<button natButton [disabled]="disabled" [size]="size" [theme]="theme">{{content}}</button>`
});

export const Default = Template.bind({})
Default.args = {...DefaultArgs, disabled: false};

Let’s reload our stories at localhost:4400.

Did you see the controls appear and our button updating when we change any of them!

I mentioned that the great thing about directives is that we can apply them to a variety of tags. Let’s see what happens if we add our directive to an anchor tag.

We copy our Template and Default export.

Change the disabled property to one called link and rename our Template to Anchor template and our export to Anchor. Lastly, we wire up our link property with the anchor tags href property and add a link to the stories args.

const AnchorTemplate: Story<ButtonDirectiveProps & {link: string}> = (args) => ({
  props: args,
  moduleMetadata: {
    imports: [ButtonDirective],
  },
  template: `<a target="_blank" [href]="link" natButton [size]="size" [theme]="theme">{{content}}</a>`
});

export const Anchor = AnchorTemplate.bind({})
Anchor.args = {...DefaultArgs, link: 'https://media.giphy.com/media/jJQC2puVZpTMO4vUs0/giphy.gif'};

Reload your storybook one more time and check out the newly added Anchor story. Click on the anchor disguised as our button and you’ll see that it works as expected.

You made it to the end of this tutorial and built an awesome button directive. And did notice how clean our stories markup was? No Tailwind classes in the markup.

What’s next?

This is my first time writing an article like this. So first of all, thanks for reading! I hope you learned something new! What’s next? You decide. Did you enjoy this article? Are you interested in learning about the Storybook setup I use for this project? What UI element should we create next? Would you rather have a video tutorial you can follow along with? Let me know in the comments.

Forem: Robin Goetz

spartan enters a new era with Zerops

A Game-Changing Partnership

Community Growth and the Need for Sustainability

Why Zerops?

What’s Next: A Production-Ready Starter Template

Celebrating the spartan Community

The Road Ahead

This is your sign(al) to try TanStack Query & Angular

What is TanStack Query?

What is server state?

It's all about the Queries!

So what is a Query again?

Why is our queryKey an array?

Why do we need a function to return our options instead of passing them in directly?

Origins of TanStack Query in React

Reactive Angular

Mutations: Update the server, invalidate the client

Is TanStack Query for components only or do directives and services work too?

How I use TanStack Query with modern Angular

Write Reusable Queries with Custom Injection Functions

Read the docs & TkDodo's blog

Always keep good Query Keys hygiene

Keep this in mind to master mutations

Be aware of await-ed Promises

Know when to use mutate or injectMutation callbacks

Got a question? Read the FAQs!

Why introduce another dependency?

So this replaces NgRx right?

What's next?

Getting Started with spartan/ui - Shadcn-like UI Components for Angular

shadcn - A game-changing UI library (for React)

spartan/ui - shadcn for Angular

brain & helm - The building blocks of spartan/ui

@spartan-ng/cli - one command to rule them all

Your first spartan app

Setting up an Nx' Angular workspace

Running create-nx-workspace

Removing boilerplate

Adding TailwindCSS

Installing @spartan-ng/cli

Installing @spartan-ng/ui-core

Setting up tailwind.config.js

Adding CSS variables

Adding our first primitive

Using our first primitive

Other available components

What's next?

SPARTAN. Type-safe Angular full-stack development powered by Analog.

The SPARTAN Stack

Nx

Angular

Analog

TailwindCSS

tRPC

Prisma

Supabase

Option 1: Connecting to supabase.com instance

Option 2: Connecting to local supabase instance

Install supabase CLI

Log into CLI

Create Supabase project

Start Supabase services

Important: Make sure Docker is running and configured correctly!

Connect to local DB

Initializing the DB

Bringing it all together

What's next

Feature: Use NestJS integration as SSR/http server #317

Which scope/s are relevant/related to the feature request?

Information

Describe any alternatives/workarounds you're currently using

I would be willing to submit a PR to fix this issue

The future is bright

Angular & signals. Everything you need to know.

Signals. A short introduction

It all started (about) 10 years ago

The challenges of automatic change detection

ZoneJs and when to check for changes

Unidirectional data flow or ExpressionChangedAfterItHasBeenCheckedError

Be aware of `await`-ed Promises

Know when to use `mutate` or `injectMutation` callbacks