As I continued embarking on more projects, working at different companies and working with different clients, I started to understand the meaning of scalable applications; one which can be easily maintained over a period of time while more features are added. This meant that I needed to move towards using a declarative approach that would let me focus less on syntax and more on functionality. Then I bumped into an article that talked about “Imperative vs Declarative Programming” and its impact on how we write code.

What is Imperative Programming?

This is a type of programming paradigm where instructions or commands need to be described explicitly for each step required during execution. With this paradigm, one is more concerned with the “how” to get a desired outcome.

const ages = [10, 20, 30, 40];
const doubledAges = [];

// We are manually managing the loop state and the array mutation
for (let i = 0; i < ages.length; i++) {
  const result = ages[i] * 2;
  doubledAges.push(result);
}

console.log(doubledAges); // [20, 40, 60, 80]

In the code snippet above, you will notice that we are giving the computer a step-by-step recipe. If we forget to initialize the doubledAges array or mess up the loop index, the code fails.

Let’s see how this compares to Declarative Programming.

What is Declarative Programming?

As the name suggests, in this approach we describe what the program does, without explicitly telling it how to do so.

const ages = [10, 20, 30, 40];

// We describe what we want: a mapped version of the original array
const doubledAges = ages.map(age => age * 2);

console.log(doubledAges); // [20, 40, 60, 80]

In the code snippet above, we don’t care how the loop works; we just define the transformation from input to output.

In the two examples above, both approaches achieve the same result, but they differ on how to go about it. Declarative programming is a layer of abstraction on top of imperative programming. It leverages on the steps already mapped out either using loops and conditionals behind the scenes or by defining an algorithm for the sole purpose of achieving a specific goal. For example, creating utility functions that one can use in their project for specific tasks.

Real case scenario: A Real-time Search Input

A search bar with real-time suggestions as a user types into it is one of the key features of any e-commerce website today. You would want your users to be able to provide search queries while also getting relevant results quickly. The goal is to:

• Listen to user input.

• Wait for the user to stop typing.

• Ignore duplicate search terms to avoid redundant queries.

• Fetch data from the server.

• Show results only for the latest search request.

Let’s look at how we would do this with an imperative approach (The “How”)

// Component variables
private searchTimeout: any;
private lastSearchTerm = '';
public results = [];

onSearch(event: any) {
  const term = event.target.value;

  // 1. Manually handle debouncing
  clearTimeout(this.searchTimeout);
  this.searchTimeout = setTimeout(() => {
    
    // 2. Check if the value is actually different
    if (term !== this.lastSearchTerm) {
      this.lastSearchTerm = term;

      // 3. Trigger the API call
      this.searchService.getResults(term).subscribe(data => {
        this.results = data; // Potential "Race Condition" bug here!
      });
    }
  }, 300);
}

In the code above, we are manually managing state variables. This to some extent is a “fragile” way because a developer could easily forget to clear a timeout or handle an out-of-order API response. If the first search takes 5 seconds and the second takes 1 second, the first search might overwrite the second search’s result when it finally arrives, leading to what we call a race condition. Manual timeouts and subscriptions can lead to memory leaks if the component is destroyed (moving from one page to another).

Let’s see how this looks with a declarative approach (The “What”)

// Define the "stream" once
readonly searchResults$ = this.searchControl.valueChanges.pipe(
  debounceTime(300),           // Wait for 300ms pause
  distinctUntilChanged(),      // Only act if the text changed
  switchMap(term =>            // Cancel previous request and switch to new one
    this.searchService.getResults(term)
  )
);

With the use of libraries such as RxJS, we treat the input as a stream. We describe the journey of the data rather than the steps that need to be taken along the way.

• Self-cleaning: switchMap automatically cancels the previous HTTP request if a new one starts, hence avoiding any potential race conditions.

• No state to manage: We don’t need lastSearchTerm or searchTimeout variables as the logic is “pure”.

• Async pipe: By using searchResults$ | async in the template (HTML), Angular handles the subscription & unsubscription automatically.

Conclusion: Engineering for Longevity

The shift from Imperative to Declarative programming is more than just a technical pivot; it’s a shift in how we handle complexity. While imperative code might feel faster to write in the short term, it creates a “hidden tax” of technical debt, where every new feature increases the risk of side effects and race conditions.

By adopting a Declarative Mindset by leveraging tools like RxJS in Angular, we move away from micro-managing the machine instructions and toward describing the logic of the business.

Why this matters for your project:

• Maintainability: New developers can understand what the system does without deconstructing how every loop is managed.

• Predictability: Pure transformations and immutable data flows mean fewer “it works on my machine” bugs.

• Scalability: Systems built on streams are naturally prepared for the high-concurrency demands of modern enterprise applications.

At Unstacked Labs, we don't just ship features; we architect solutions that are resilient to change. Whether we are optimizing an Angular frontend or scaling a backend architecture, our commitment to declarative principles ensures that your codebase remains an asset, not a liability.

It's pretty common nowadays to find web developers specializing in a single framework. While there is nothing wrong with that, as long as you stick to its strengths, i.e., the right tool for the right job. The saying goes, "when you have a hammer, everything is a nail," and I have seen frontend developers who want to use the only Framework they know for everything, despite it not being the right fit for the task at hand.

Some Background

Before I can go any further, let me give you some context. I am from Kenya, and most of my friends have $200 or lower smartphones, and about half of those have a $100 or lower smartphone; some don't even have smartphones. This means the devices most of my friends own are quite limited performance-wise. And this is one crucial area we as developers need to understand as we tend to have more powerful devices at our disposal.

The other thing to be aware of is the state of internet connectivity. It's pretty decent, maybe even good, in some areas, primarily Urban areas, but the speed and reliability fall off the cliff when you start heading to informal settlements and rural areas. This trend can be replicated all over Africa, and I believe in large parts of the world.

Performance

So, why am I telling you this? When it comes to performance, you need to approach it in two folds: First, the number of KBs the user has to download and the device's capability the user has. The internet speed is impacted by the device in question capabilities, not just the internet coverage. Users with low-end devices tend to also live in areas with poor internet coverage and connectivity.

The more the KBs your JS script is, the longer it will take to download the script before we can get to parsing, which will also be slower due to device capability limitations. As you can imagine, both of these can take a frustrating longer time on a low-end device on a slow network. When we develop poor-performing websites, i.e., takes longer to load, huge scrips that take a toll on the processor and battery life, we negatively impact our users, especially the already disadvantaged.

When I am using my iPhone 13 Pro Max (or whatever the latest model is as you are reading this) on the latest 5g network, I will probably notice slow performance, but it will be a minor inconvenience. However, for someone on a $100 or lower smartphone on a slow network, the impact on performance will be huge. We have all been there, trying to load a website that refuses to load or is laggy either due to poor network connection or the toll the website places on both memory and the process. This could mean the difference between someone getting life-saving information in time or not getting it.

SPAs

One of the most popular ways of developing websites is using Single Page Applications (SPAs) frameworks popularized by React and Angular. These SPA frameworks have become a go-to for developers due to their excellent developer experience and ease of building websites, but this comes at a performance cost. SPA applications need to be bootstrapped, which means you ship your site in JavaScript for the browser to download, parse and render your website in what is known as Client-Side Rendering (CSR).

So, to recap, the user not only needs to download the Framework Code + your Application code, but they also need the browser to parse it before they can see content on your site. Depending on the size of the Framework and other libraries' sizes, this can quickly balloon to MBs of data.

Due to the above issues, we have come up with techniques to try and show the content as soon as possible such as Server-Side Rendering (SSR) and Static Site Generation (SSG). But these are not perfect solutions. They both need to put the Framework back into the rendered HTML after the initial content has been displayed for any interactivity, in a process called hydration.

This is okay (ish) if you are building a web app such as Facebook or YouTube (guess who is behind two of the most used SPA frameworks), where once the site loads, you can access a bazillion of content without having to load the site again. The examples I mentioned above behave more like apps than traditional websites.

In such instances, I may be okay paying the upfront tax, but subsequent navigations are faster, and requests and data exchange between the server and the client is more efficient. This, of course, is computationally expensive as the Framework in question has to update the DOM to create and removes nodes so that views can change.

But what if all I wanted to access was information on a single page? Think of a blog post or some instruction on applying for a government grant or social benefits. Do I have to download and run a whole web app to access this information?

As you can imagine, this can be very painful, especially for government sites, NGOs, and business services whose customer base has users with poor internet coverage and low-end devices or a combination of both.

To be honest, this should extend to everyone, no matter the internet connection speed or kind of device I have; I shouldn't have to download tons of JS code just to read your blog post.

In Conclusion

So, where am I going with this? The title of this article is "The Right Tool for the Right Job." I mean that as developers, we need to think about our users and the purpose of what we are building before choosing the tools to use. Whatever tools and frameworks we use, we need to emphasize more on the user experience we are providing. This means that we need to learn to have more than one tool in our toolkit and be open to learning more. Lately, we have seen an uptick in frameworks and libraries geared towards 0KB Javascript without sacrificing developer experience. I believe every front-end developer should know at least one.

We have a lot of tools at our disposal from SPAs frameworks such as Angular, React, Vue, etc., which have their use cases but should not be used for everything. On the other hand, we have frameworks and tools for building Multi-Page Applications (MPAs) and Static Sites, such as Astro, Hugo, Jekyll, etc., that are designed for shipping as little Javascript as possible while providing incredible speeds most SPAs frameworks can only dream off.

My point is as a developer; you should make sure you have a few of these tools in your tool kit; this will ensure that whenever you are choosing, you choose the right tool for the job.

Due to how trends work, it is easy for methods/tools to go out of fashion. This is not because it is less effective but because developers stop using them in favor of something else. This is what happened with Multi-Page Applications (MPAs), as developers started adopting popular web frameworks such as Angular, React, Vue, etc. This led to an uptick in SPA usage as the frameworks became more popular.

Due to how SPAs work, the impact has been that the amount of Javascript we ship to the browser has increased. i.e., you can't have a react web app without React to manage state and rendering. SPAs use Javascript to render the HTML to be displayed in the browser. In many cases, this makes sense, for instance, in web apps such as Facebook or YouTube, where managing the state is paramount. But in other cases, this does not make sense, for example, blogs, personal portfolios, etc.

Server-Side Rendering

When using a framework such as Angular or React and SPAs in general, the server does very little; all the rendering is done on the Client-Side, in what is known as Client-Side Rendering. To see the content, you first have to download the framework's runtime (JS needed to scaffold your web app) and also need an environment to render the content, i.e., the browser.

This has a few downsides, the notable ones being it's slow to show something on the screen, the impact of this is worse on low-end devices and slower internet connection and Search Engine Optimization - bots and crawlers are usually unable to render these pages and can't parse the content to show results.

We have two standard solutions to solve the above problems: Server-Side Rendering (SSR) and Rendering during build time - SSG. SSG is similar to SSR but at build time, removing the need to render on every request at the server. SSG is common for sites whose content isn't that dynamic. The problem with these two solutions is that they don't solve the problem with SPAs but rather postpone it.

If you want any sort of interactivity, say opening and closing the navbar on your web app, you will need to hydrate your rendered app from either SSG or SSR. This is the process of bootstrapping the framework you are using, transferring the state from the server so that the framework can take over. This usually happens after the first content is painted (after rendering the server-side rendered HTML from the server) but before the interactivity in your web app.

This means the JS needed by your framework has to be downloaded and parsed, and the user has to wait for all that to happen to interact with your web app. This would mean even on pages where you don't need interactivity, i.e., About Us Page, Terms and Conditions, etc., you still need to do all that, which is a bit unnecessary.

Islands

And this is where Islands Architecture comes in. Imagine this; what if you could create your web app with pure HTML and CSS for all the static content but then add in regions of dynamic content or interactivities - islands - that can use a framework to add interactivity. These regions would use any framework, and the framework runtime would only be downloaded only when on a page that uses it rather than on the initial load of the website.

Web frameworks such as Astro (My website is built with Astro), Marko, and most recently Qwik, among others, are implementing this architecture method. In the case of Astro, you have Astro components that use some variation of JSX but do not have a client-side state, so there is no runtime.

Astro

Astro uses the concept of JS opt-in, meaning by default, no Javascript is generated unless you tell Astro to include javascript. You can then either use Vanilla JS to include Javascript - the old fashioned way, as shown below:

Astro components cannot be hydrated as they are HTML only templating components and any Javascript needs to be included as indicated above or via a framework such as React, SolidJS, etc.

The second option is to bring your framework, for example, React, Preact, Lit, Svelte, Vue, etc., to create components that add regions of interactivity (islands) in your web app.

// index.astro file
---
import ReactComponent from "./ReactComponent"

---

<ReactComponent />

You are also in control of when the necessary region is hydrated. This is done via directives that instruct Astro when to perform hydration. For instance, you might want an island to be hydrated on load or only when it becomes visible. There are several directives to help you achieve this, which you can learn more about here.

Marko and Qwik

While I am not an expert at either Marko.js or Qwik (the new kid in the block), I will link additional resources below if you are interested in learning more. Marko and Qwik take the concept of islands a little further when compared to Astro.

Marko is an MPA framework, and its Island architecture is a bit smarter in that it automatically decides to load JS needed for an Island, delaying it as far as possible, allowing for far more efficient islands. This is unlike the current Astro approach, which relies on the developer to tell Astro when to do hydration. Astro is still in the pre-release stage, and maybe this will change in the future.

Another key advantage Marko has over Astro is that Marko decides what is inside the Islands and what's not in it. This means components such as footers, headers, etc., that only display static content don't become islands, while forms and other rich components with dynamic content become islands that can be hydrated.

Qwik, on the other hand, takes this to a component level, breaking down how hydration is done so that it is done only when needed. This is achieved by aggressively breaking apart your website's JavaScript into multiple chunks, setting up global event listeners, and serializing points of interest directly into the HTML. For each distinct user interaction, Qwik has all it needs to load only the code required to perform the action and nothing more.

In return, this leads to smaller chunks, which are faster to load, parse and load only what the user needs. This is known as progressive hydration, which is out of scope for this article, and hopefully, I will write about it soon.

Conclusion

This article looked at Islands Architecture, why they exist, and the frameworks currently applying them. In the next series of articles, I want to dig deeper into the frameworks mentioned above - Astro, Marko, and Qwik, plus other frameworks such as Svelte, Angular, and React and how they differ internally from each other.

Resources

1. Why Progressive Hydration is Harder than You Think

2. From Static to Interactive: Why Resumability is the Best Alternative to Hydration

3. JavaScript vs. JavaScript. Fight!

4. Why Efficient Hydration in JavaScript Frameworks is so Challenging

5. Resumable JavaScript with Qwik

6. Conquering JavaScript Hydration Event delegation is the key to not running over the component... Apr 15

7. State of JavaScript 2021: Framework Reflections

8. A first look at Qwik - the HTML first framework WRITTEN BYMIŠKO HEVERY JULY 2, 2021

This journey will take us through leveraging the power of Firebase, the rich data of the TMDB API, and the cutting-edge capabilities of Google's Gemini models orchestrated by the Genkit framework. We'll explore a practical, secure, and scalable architectural approach, showcasing how these powerful technologies integrate seamlessly to enhance user engagement and transform your application into a truly smart entertainment hub.

An AI-powered recommendation engine, powered by Genkit

Our fictional movie and TV shows hub, “Nova Reel”, is an Angular-based application for browsing, discovering, and getting personalized recommendations for movies and TV shows. It leverages Google's Genkit AI platform to provide intelligent recommendations based on user favorites.

Nova Reel app: https://nova-reels.web.app/

GitHub Repo: https://github.com/waynegakuo/nova-reel

Screenshot of the Nova Reel web application

Key Features

• 🔥 Browse trending movies and TV shows

• 🔍 Filter content by categories (Popular, Top Rated, Now Playing, etc.)

• 🔎 Search for specific titles

• ℹ️ View detailed information about movies and TV shows

• ⭐ Save favorites for quick access

• 🤖 Get AI-powered personalized recommendations based on your favorites

• 📱 Responsive design for all devices

🏗️ Architecture

Nova Reel is built with a modern tech stack that combines frontend and backend technologies:

🖥️ Frontend

• 🅰️ Angular: The frontend is built with Angular, using standalone components and signals for reactive state management

• 🔐 Firebase Authentication: For user authentication and management

• 🗄️ Firebase Firestore: For storing user favorites and preferences

• 🔥 Angular Fire: For integrating Firebase services with Angular

☁️ Backend

• ⚡ Firebase Functions: Serverless backend functions that handle API requests and AI processing

• 🧠 Genkit: Google's AI platform for building generative AI applications

• 💫 Gemini 2.5 Pro: The underlying AI model used for generating recommendations

• 🎞️ TMDB API: External API for fetching movie and TV show data

🤖 AI Recommendation Engine

The heart of Nova Reel is its AI recommendation engine, which uses Genkit to analyze user favorites and generate personalized recommendations:

1. 📊 Data Collection: The app stores user favorites in Firebase Firestore

2. 🧠 AI Processing: When a user requests recommendations, the app calls a Firebase Function that uses Genkit to:

   • 📥 Fetch the user's favorites from Firestore

   • 🔄 Create a context from these favorites to inform the AI

   • 💫 Use the Gemini 2.5 Pro model to generate personalized recommendations

   • 💡 Provide reasoning for the recommendations

3. 📱 Recommendation Display: The frontend displays these recommendations in the "For You" tab, along with the AI's reasoning

Why use Genkit?

1. Smart Data Integration (Retrieval Augmented Generation—RAG): the AI fetches your favorites from Firestore, then dynamically queries TMDB as it “thinks” using our getTmdbDataTool. This grounds the AI in your real data, leading to highly relevant recommendations.

2. AI-Driven Actions (Tool Calling): Our AI uses the getTmdbDataTool to fetch data from TMDB. It’s like giving the AI its own web browser and search engine. This empowers the AI to reason and retrieve information for better suggestions.

3. Robust Backend & Security: Our AI logic runs on Firebase Cloud Functions.

   1. Secure API Keys: TMBD & Gemini keys stay safely hidden on the server.

   2. Complex logic offloaded: Keeps the heavy lifting off the user’s device.

4. Debugging & Observability: Genkit comes with a Developer UI and Firestore tracing. We can literally see:

   1. What prompt did the AI receive?

   2. What “tools” it decided to call.

   3. The exact data returned by those tools.

   4. The AI’s final reasoning.

NB: This guide assumes you have Angular CLI (v19 or later), Node.js (v20+), npm, and Git installed. If not, kindly check out the GitHub Repo for the requirements for this project.

🔥 Firebase Project Setup & TMDB API Key

🏗️ Create a Firebase Project:

1. Go to Firebase Console.

2. Click "Add project" and follow the prompts to create your project.

3. ⚠️ Important: Upgrade your project to the Blaze (pay-as-you-go) plan. Cloud Functions and Vertex AI (which Genkit uses) require a billing-enabled project. Don't worry, free tiers are generous for testing.

☁️ Enable Essential Google Cloud APIs

Your Firebase project uses Google Cloud behind the scenes. For secure secret management, the Secret Manager API must be enabled. Other necessary APIs (like Cloud Functions, Cloud Build, Cloud Run, Vertex AI) are usually enabled automatically by Firebase when you deploy functions or use AI features.

• Go to the Google Cloud Console for your Firebase project.

• In the navigation menu, go to APIs & Services > Enabled APIs & Services.

• Click on +Enable APIs and services.

• Search for and enable the Secret Manager API.

🛠️ Install Firebase CLI:

Note for Firebase Studio users: Skip step 2 (npm install command) and go directly to step 3 (firebase login).

1. Open your terminal/command prompt.

2. Install the Firebase CLI globally:

npm install -g firebase-tools

1. Log in to Firebase:

firebase login

🚀 Initialize Firebase in Your Project:

1. Navigate to your project's root directory (you should already be there after cloning the repository).

2. Initialize Firebase:

firebase init

3. Select "Functions" and "Firestore" when prompted.

4. Choose your existing Firebase project to link to.

5. Select TypeScript for functions (highly recommended).

6. For Firestore, accept the default rules file (you can change it later).

7. Do NOT overwrite existing files if prompted.

🔄 Update the .firebaserc File:

You can update the .firebaserc file in two ways:

Option 1: Using Firebase CLI (Recommended)

Run the following command to set your Firebase project ID:

firebase use YOUR_PROJECT_ID

Replace YOUR_PROJECT_ID with the project ID of the Firebase project you created. This command will automatically update your .firebaserc file.

Option 2: Manual Editing

1. Open the .firebaserc file in your project root directory.

2. Replace the default project name with your Firebase project ID:

{
  "projects": {
    "default": "YOUR_PROJECT_ID"
  }
}

Replace YOUR_PROJECT_ID with the project ID of the Firebase project you created.

🔥 Add Firebase Configuration to Your Project:

1. Go to your Firebase project in the Firebase Console.

2. Click on the gear icon (⚙️) next to "Project Overview" and select "Project settings".

3. Scroll down to the "Your apps" section and select your web app (or create one if you haven't already).

4. Under the "SDK setup and configuration" section, select "Config" to view your Firebase configuration object.

5. Copy the configuration object that looks like this:

{
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_PROJECT_ID.appspot.com",
  messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
  appId: "YOUR_APP_ID",
  measurementId: "YOUR_MEASUREMENT_ID"
}

6. Open the environment files in your project:

• For production: src/environments/environment.ts

• For development: src/environments/environment.development.ts

7. Replace the existing firebaseConfig object with your own Firebase configuration:

export const environment = {
  production: true, // or false for environment.development.ts
  firebaseConfig: {
    apiKey: "YOUR_API_KEY",
    authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
    projectId: "YOUR_PROJECT_ID",
    storageBucket: "YOUR_PROJECT_ID.appspot.com",
    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
    appId: "YOUR_APP_ID",
    measurementId: "YOUR_MEASUREMENT_ID"
  }
};

🎬 Get TMDB API Key:

1. Go to TMDB.

2. Sign up or log in.

3. Go to your user profile (click your avatar) -> Settings -> API.

4. Request a new API key (Developer/v3).

5. Note down your API Read Access Token (Bearer Token). It starts with "eyJ...".

🔐 Set TMDB API Key as Firebase Secret:

1. Navigate to your functions directory:

cd functions

2. Set the TMDB API key as a Firebase secret:

firebase functions:secrets:set TMDB_API_BEARER_TOKEN

3. Paste your TMDB Bearer Token when prompted.

4. Return to the project root:

cd ..

🔑 API Keys and Deployment

1. 🔑 Set up your API keys:

• Create a .env file in the functions directory with your Gemini API key (for local development):

cd functions
echo "GEMINI_API_KEY=your_gemini_api_key" > .env
cd ..

• Set up the Gemini API key as a Firebase secret (for production deployment):

firebase functions:secrets:set GEMINI_API_KEY

Note: When running this command, you'll be prompted to enter the actual secret value. The GEMINI_API_KEY is needed both as an environment variable (for local development) and as a Firebase secret (for production deployment).

2. 🔥 Configure Firebase:

firebase use your-project-id

3. 🚀 Deploy Firebase Functions:

firebase deploy --only functions

4. 🏃‍♂️ Run the application locally:

ng serve

🧠 Building an AI Recommendation Engine with Genkit

Nova Reel demonstrates how to build an AI recommendation engine using Genkit. Here's how it works:

1️⃣ Setting Up Genkit

In the Firebase Functions (functions/src/index.ts), Genkit is configured with the Gemini model:

// Configure Genkit
const ai = genkit({
  plugins: [
    googleAI({apiKey: process.env.GEMINI_API_KEY }),
  ],
  model: googleAI.model('gemini-2.5-pro'), // Specify your Gemini model
});

2️⃣ Creating a Custom Tool for TMDB Data

A custom tool is defined to allow the AI to fetch movie and TV show data from TMDB:

export const getTmdbDataTool = ai.defineTool(
  {
    name: 'getTmdbData',
    description: 'Fetches movie or TV show data from TMDB using specific endpoint, ID, or query.',
    inputSchema: z.object({
      endpoint: z.string().describe('TMDB API endpoint (e.g., "movie", "tv", "search/movie")'),
      id: z.number().optional().describe('ID for specific movie/TV show'),
      query: z.string().optional().describe('Search query string'),
    }),
    outputSchema: z.any().describe('JSON data from TMDB API response'),
  },
  async ({ endpoint, id, query }) => {
    const url = constructTmdbUrl(endpoint, { id, query });
    return await executeTmdbRequest(url, 'getTmdbDataTool');
  }
);

3️⃣ Defining the Recommendation Flow

A Genkit flow is defined to handle the recommendation process:

export const _getRecommendationsFlowLogic = ai.defineFlow(
  {
    name: 'getRecommendationsFlow',
    inputSchema: RecommendationInputSchema,
    outputSchema: RecommendationOutputSchema,
  },
  async (input) => {
    // Fetch user's favorite movies/tv shows from Firestore
    const userFavoritesRef = db.collection('users').doc(input.userId).collection('favorites');
    const favoritesSnapshot = await userFavoritesRef.get();
    const favoriteItems = favoritesSnapshot.docs.map(doc => doc.data());

    // Prepare context for the AI from user favorites
    let favoritesContext = favoriteItems.map(item =>
      `${item['type'] === 'movie' ? 'Movie' : 'TV Show'}: ${item['title']} (TMDB ID: ${item['tmdbId']})`
    ).join('; ');

    // Generate recommendations using the AI model
    const { output } = await ai.generate({
      tools: [getTmdbDataTool], // Make the TMDB data tool available to the model
      prompt: `
        You are a highly intelligent movie and TV show recommendation assistant.
        The user has a list of favorite movies and TV shows.
        User's favorites: ${favoritesContext}

        Based on these favorites, recommend ${input.count} additional movies or TV shows that the user might enjoy.
        Consider their genres, actors, directors, themes, and overall vibe.
        Prioritize items with high TMDB ratings.
        Avoid recommending any of the items already in the user's favorites list.
        
        For each recommendation, provide the title, whether it's a "movie" or "tv" show, its TMDB ID, 
        a brief overview, and its poster path.
        
        Explain your reasoning briefly after the recommendations.
      `,
      output: {
        format: 'json',
        schema: RecommendationOutputSchema,
      },
    });

    return output || { recommendations: [], reasoning: 'Unable to generate recommendations.' };
  }
);

4️⃣ Exposing the Flow as a Firebase Function

The flow is exposed as a callable Firebase Function:

export const getRecommendationsFlow = onCallGenkit(
  {
    secrets: [TMDB_BEARER_TOKEN],
    region: 'africa-south1',
    cors: true,
  },
  _getRecommendationsFlowLogic
);

5️⃣ Calling the Function from the Frontend

In the frontend (src/app/services/media/media.service.ts), the function is called to get recommendations:

async getAiRecommendationsData(count: number = 5): Promise<AiRecommendationResponse> {
  const userId = this.authService.getUserId();
  if (!userId) {
    throw new Error('User must be authenticated to get AI recommendations');
  }

  const callableGetRecommendations = httpsCallable(this.functions, 'getRecommendationsFlow');
  try {
    const result = await callableGetRecommendations({
      userId: userId,
      count: count
    });
    return result.data as AiRecommendationResponse;
  } catch (error: any) {
    console.error('Error fetching AI recommendations from Cloud Function:', error);
    throw error;
  }
}

6️⃣ Displaying Recommendations

The recommendations are displayed in the "For You" tab of the landing page, along with the AI's reasoning for the recommendations.

📝 Usage

1. 🔍 Browse Content: Use the "Movies" and "TV Shows" tabs to browse trending content

2. ℹ️ View Details: Click on any movie or TV show to view detailed information

3. ⭐ Add to Favorites: Click the "Add to Favorites" button on any movie or TV show detail page

4. 🤖 Get Recommendations: Navigate to the "For You" tab to see personalized recommendations based on your favorites

5. 🔄 Refresh Recommendations: Click the "Refresh Recommendations" button to get new recommendations

Next Steps: A Series of Smart AI Features

This recommendation engine is just the beginning. Our architecture, built on Genkit, provides a flexible foundation for a series of new AI-powered features. As a next step, we will continue this journey by:

1. "Guess the Movie" from a Screenshot: We'll build a feature that allows users to upload a screenshot of a movie scene. Our AI agent, using a vision-enabled Gemini model, will analyze the image to identify the title, which will then be verified with the TMDB API to provide accurate information.

2. Mood-Based Recommendations: We'll introduce a feature that lets users dictate their mood (e.g., "I want a thrilling, suspenseful movie") in natural language. Our AI will understand the sentiment and keywords to recommend movies that match the user's emotional state, moving beyond simple genre filtering.

3. An Interactive Chatbot: We will create a conversational agent that can handle multi-turn requests. Users can ask questions like "Who directed this movie?" or give commands like "Add this to my watchlist," and the AI will use its tools to perform these actions in a conversational manner.

By adding these features, we can turn a simple recommendation app into a much more dynamic and user-friendly experience, with Genkit acting as the intelligent layer that makes it all possible. This approach demonstrates how AI can be a central part of an application's architecture, not just a supporting tool.

Conclusion

Personalized recommendation engines have evolved from a novelty to an essential part of the modern digital experience. This article has showcased a practical approach to building a robust and intelligent recommender system for movies and TV shows. By leveraging Firebase Cloud Functions, we can securely handle API keys and offload complex logic from the frontend. Using Firestore, we efficiently store and retrieve user-specific data, forming the basis for personalization. Finally, by integrating the Genkit framework, we empower the Google Gemini model to act as a data-aware AI agent.

This architecture allows the AI to autonomously "reason" and "act" by calling a tool that connects to the TMDB API, enabling it to fetch real-time data to ground its recommendations. This multi-step, server-side process ensures the suggestions are not only personalized but also accurate and reliable. The result is a seamless and engaging user experience that goes beyond simple content matching.

The ongoing advancements in AI promise even greater innovation in this field, with future systems likely to incorporate more explainable AI for transparency, federated learning for privacy, and real-time adaptations to user behavior. The pursuit of creating a frictionless and truly tailored entertainment experience will continue to be a driving force, with AI playing an increasingly central role.

1. Foundation: The Decorator Pattern

The Decorator Pattern is a structural design pattern that attaches new behaviors to objects by placing them inside special wrapper objects, called decorators. This allows you to add functionality without modifying the original class. Go straight to the code [github repo]

// Classical Decorator Pattern Example
class Coffee {
  cost() { return 5; }
}
class MilkDecorator {
  constructor(private coffee: Coffee) {}
  cost() { return this.coffee.cost() + 1; }
}
const milkCoffee = new MilkDecorator(new Coffee());
console.log(milkCoffee.cost()); // 6

TypeScript 5.0+ decorators are inspired by this concept: they let you add behavior or metadata to classes, methods, and properties in a declarative, compile-time manner.

In Typescript versions lesser than 5.0, decorators have a different implementation. Here is the link to an article covering lower versions: Typescript Decorators (Pre-v5.0)

TypeScript for a while had support for "experimental" decorators for years. While these experimental decorators have been incredibly useful, they modeled a much older version of the decorators proposal, and always required an opt-in compiler flag called --experimentalDecorators. Any attempt to use decorators in TypeScript without this flag used to prompt an error message.

According to this announcement, --experimentalDecorators will continue to exist for the foreseeable future; however, without the flag, decorators will now be valid syntax for all new code. Outside of --experimentalDecorators, they will be type-checked and emitted differently. The type-checking rules and emit are sufficiently different that while decorators can be written to support both the old and new decorators behavior, any existing decorator functions are not likely to do so.

2. TypeScript 5.0+ Decorators: Basics & Parameters

To use the new decorator API in TypeScript 5.0+, configure your tsconfig.json:

{
  "target": "ESNext",
  "module": "ESNext",
  "experimentalDecorators": true,
  "useDefineForClassFields": true
}

2.1 Types of Decorators & Their Parameters

Parameter Details

• Class Decorator: Receives the class constructor and returns it (or a new constructor).

• Field Decorator: Receives a context object and returns a function that processes the field value.

• Method Decorator: Receives a context object and can use addInitializer to modify the method.

• Accessor Decorator: Receives a context object for getter/setter methods.

// New API Examples
function MyClassDecorator<T extends new (...args: any[]) => any>(constructor: T): T {
  console.log('Class created:', constructor.name);
  return constructor;
}

function MyFieldDecorator<T extends object, K extends keyof T>(
  target: undefined, 
  context: ClassFieldDecoratorContext<T, T[K]>
): (value: T[K]) => T[K] {
  return (value: T[K]) => value;
}

function MyMethodDecorator<T extends object>(
  target: undefined,
  context: ClassMethodDecoratorContext<T, (this: T, ...args: any[]) => any>
): void {
  context.addInitializer(function (this: T) {
    // Modify the method here
  });
}

Example Recap:

class Example {
  @MyFieldDecorator
  someProperty: string = "hello";

  @MyMethodDecorator
  someMethod(msg: string) {}
}

Decorators execute at compile/design time. You can modify behavior or attach annotations used by frameworks.

3. Reflection & Metadata

To read design-time types at runtime, use reflect-metadata:

1. Install: npm install reflect-metadata

2. Import once: import 'reflect-metadata';

3. Enable emitDecoratorMetadata in tsconfig.json.

// Retrieve the type of a property
Reflect.getMetadata('design:type', target, propertyKey);

Reflection lets decorators inspect types, useful for form builders, DI, or validation.

4. Angular Built-in Decorators

Angular started using decorators long before TC39 finalized the spec — and relied on TypeScript’s experimental decorators. Although under the hood Angular relies on TypeScript’s standard compiler, it has its own Angular compiler (ngc) that processes the decorators and generates code for templates, DI, etc. See The Dance of Decorated Classes: Inside the Angular Compiler. Hence, ngc can be said to be an extension TypeScript compiler which knows how to “execute” Angular decorators, applying their effects to the decorated classes at build time.

5. Writing Custom Decorators (New API)

5.1 Class Decorator

function LogClass<T extends new (...args: any[]) => any>(constructor: T): T {
  console.log('Class created:', constructor.name);
  return constructor;
}

@LogClass
class MyService {}

5.2 Method Decorator

function LogMethod<T extends object>(
  target: undefined,
  context: ClassMethodDecoratorContext<T, (this: T, ...args: any[]) => any>
): void {
  const methodName = context.name;
  context.addInitializer(function (this: T) {
    const originalMethod = this[methodName as keyof T] as (this: T, ...args: any[]) => any;
    (this as any)[methodName] = function (this: T, ...args: any[]) {
      console.log(`Calling ${String(methodName)} with`, args);
      return originalMethod.call(this, ...args);
    };
  });
}

5.3 Field Decorator

function DefaultValue<T extends object, K extends keyof T>(
  defaultValue: T[K]
) {
  return function (
    target: undefined, 
    context: ClassFieldDecoratorContext<T, T[K]>
  ): (value: T[K]) => T[K] {
    return (value: T[K]) => value ?? defaultValue;
  };
}

class Example {
  @DefaultValue("hello")
  message: string;
}

5.4 Accessor Decorator

function Validate<T extends object>(
  target: undefined,
  context: ClassAccessorDecoratorContext<T, any>
): void {
  context.addInitializer(function (this: T) {
    const originalGet = this[context.name as keyof T] as any;
    const originalSet = context.access.set;
    
    context.access.set = function (value: any) {
      if (value === undefined || value === null) {
        throw new Error(`${String(context.name)} cannot be null or undefined`);
      }
      originalSet.call(this, value);
    };
  });
}

6. Decorator Factories & Composition

6.1 Decorator Factories

A decorator factory is a function that returns a decorator, allowing you to pass arguments/configuration.

function LogWithPrefix(prefix: string) {
  return function <T extends object>(
    target: undefined,
    context: ClassMethodDecoratorContext<T, (this: T, ...args: any[]) => any>
  ): void {
    const methodName = context.name;
    context.addInitializer(function (this: T) {
      const originalMethod = this[methodName as keyof T] as (this: T, ...args: any[]) => any;
      (this as any)[methodName] = function (this: T, ...args: any[]) {
        console.log(`${prefix}: ${String(methodName)}`, args);
        return originalMethod.call(this, ...args);
      };
    });
  };
}

class Example {
  @LogWithPrefix('DEBUG')
  say(message: string) {
    console.log(message);
  }
}

6.2 Decorator Composition

Decorator composition means stacking multiple decorators on a single target. Decorators are applied bottom to top (the last decorator in code is applied first).

function Log<T extends object>(
  target: undefined,
  context: ClassMethodDecoratorContext<T, (this: T, ...args: any[]) => any>
): void {
  const methodName = context.name;
  context.addInitializer(function (this: T) {
    const originalMethod = this[methodName as keyof T] as (this: T, ...args: any[]) => any;
    (this as any)[methodName] = function (this: T, ...args: any[]) {
      console.log('Calling', String(methodName));
      return originalMethod.call(this, ...args);
    };
  });
}

function Cache<T extends object>(
  target: undefined,
  context: ClassMethodDecoratorContext<T, (this: T, ...args: any[]) => any>
): void {
  const methodName = context.name;
  const cache = new Map<string, any>();
  
  context.addInitializer(function (this: T) {
    const originalMethod = this[methodName as keyof T] as (this: T, ...args: any[]) => any;
    (this as any)[methodName] = function (this: T, ...args: any[]) {
      const cacheKey = JSON.stringify(args);
      if (cache.has(cacheKey)) {
        return cache.get(cacheKey);
      }
      const result = originalMethod.call(this, ...args);
      cache.set(cacheKey, result);
      return result;
    };
  });
}

class MathService {
  @Log
  @Cache
  expensiveOperation(x: number) {
    return x * x; // pretend this is slow
  }
}

7. Real-World Use Cases

7.1 Permission Check

function RequirePermission(permission: string) {
  return function <T extends object>(
    target: undefined,
    context: ClassMethodDecoratorContext<T, (this: T, ...args: any[]) => any>
  ): void {
    const methodName = context.name;
    context.addInitializer(function (this: T) {
      const originalMethod = this[methodName as keyof T] as (this: T, ...args: any[]) => any;
      (this as any)[methodName] = function (this: T, ...args: any[]) {
        const svc = inject(PermissionService);
        if (!svc.hasPermission(permission)) {
          throw new Error(`Missing ${permission}`);
        }
        return originalMethod.call(this, ...args);
      };
    });
  };
}

7.2 Caching

const cache = new Map<string, any>();
function CacheResult<T extends object>(
  target: undefined,
  context: ClassMethodDecoratorContext<T, (this: T, ...args: any[]) => any>
): void {
  const methodName = context.name;
  context.addInitializer(function (this: T) {
    const originalMethod = this[methodName as keyof T] as (this: T, ...args: any[]) => any;
    (this as any)[methodName] = function (this: T, ...args: any[]) {
      const ckey = `${String(methodName)}-${JSON.stringify(args)}`;
      if (cache.has(ckey)) return cache.get(ckey);
      const res = originalMethod.call(this, ...args);
      cache.set(ckey, res);
      return res;
    };
  });
}

7.3 Analytics on Component Init

function WithAnalytics(eventName?: string) {
  return function <T extends new (...args: any[]) => any>(constructor: T): T {
    const originalInit = constructor.prototype.ngOnInit;
    constructor.prototype.ngOnInit = function () {
      const analytics = inject(AnalyticsService);
      analytics.trackEvent('Init', { name: eventName || constructor.name });
      originalInit?.apply(this);
    };
    return constructor;
  };
}

7.4 Auto-Unsubscribe

function AutoUnsubscribe<T extends new (...args: any[]) => any>(constructor: T): T {
  const originalDestroy = constructor.prototype.ngOnDestroy;
  constructor.prototype.ngOnDestroy = function () {
    for (const k in this) {
      this[k]?.unsubscribe?.();
    }
    originalDestroy?.apply(this);
  };
  return constructor;
}

8. Bonus: Simple Signals & Observables

Bonus Simple Signal inspired by Angular Signal and a custom fromObservable you can use to try out the @AutoUnsubscribe.

8.1 SimpleSignal

function SimpleSignal<T>(initial: T) {
  let value = initial;
  const listeners: (() => void)[] = [];
  const signal = (() => value) as (() => T) & {
    set: (v: T) => void;
    effect: (fn: () => void) => void;
  };
  signal.set = v => { value = v; listeners.forEach(fn => fn()); };
  signal.effect = fn => { listeners.push(fn); fn(); };
  return signal;
}

8.2 fromObservable

import { Observable } from 'rxjs';
function fromObservable<T>(obs$: Observable<T>, initial: T) {
  const sig = SimpleSignal(initial);
  const sub = obs$.subscribe(val => sig.set(val));
  (sig as any).unsubscribe = () => sub.unsubscribe();
  return sig;
}

9. Code Lab: Debounce Decorator

Objective: Create a @Debounce method decorator that delays method execution.

function Debounce(ms: number) {
  return function <T extends object>(
    target: undefined,
    context: ClassMethodDecoratorContext<T, (this: T, ...args: any[]) => any>
  ): void {
    const methodName = context.name;
    let timeoutId: NodeJS.Timeout;
    
    context.addInitializer(function (this: T) {
      const originalMethod = this[methodName as keyof T] as (this: T, ...args: any[]) => any;
      (this as any)[methodName] = function (this: T, ...args: any[]) {
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
          originalMethod.call(this, ...args);
        }, ms);
      };
    });
  };
}

Usage:

class SearchComponent {
  @Debounce(300)
  onSearch(query: string) {
    // This will only execute after 300ms of no calls
  }
}

10. Migration from Legacy API

Key Differences:

Migration Example:

Legacy:

function LogMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    console.log(`Calling ${propertyKey}`, args);
    return original.apply(this, args);
  };
  return descriptor;
}

New API:

function LogMethod<T extends object>(
  target: undefined,
  context: ClassMethodDecoratorContext<T, (this: T, ...args: any[]) => any>
): void {
  const methodName = context.name;
  context.addInitializer(function (this: T) {
    const originalMethod = this[methodName as keyof T] as (this: T, ...args: any[]) => any;
    (this as any)[methodName] = function (this: T, ...args: any[]) {
      console.log(`Calling ${String(methodName)}`, args);
      return originalMethod.call(this, ...args);
    };
  });
}

11. Best Practices & Summary

• Keep decorators small and single-purpose

• Prefer decorator factories for configurability

• Document execution order if it matters

• Understand evaluation and application order: decorators are applied bottom-to-top

• Use reflection for advanced scenarios (type inspection, DI, validation)

• Leverage composition to separate concerns and reuse logic

• Use the new API for TypeScript 5.0+ projects

• Consider migration from legacy API for better performance and features

🎉 You now have a complete advanced reference for TypeScript 5.0+ decorators, including real-world use cases, composition, and migration guidance.

The Decorator Pattern is a structural design pattern that attaches new behaviors to objects by placing them inside special wrapper objects, called decorators. This allows you to add functionality without modifying the original class. To jump straight to the code: [github repo]

// Classical Decorator Pattern Example
class Coffee {
  cost() { return 5; }
}
class MilkDecorator {
  constructor(private coffee: Coffee) {}
  cost() { return this.coffee.cost() + 1; }
}
const milkCoffee = new MilkDecorator(new Coffee());
console.log(milkCoffee.cost()); // 6

TypeScript legacy decorators are inspired by this concept: they let you add behavior or metadata to classes, methods, and properties in a declarative, compile-time manner.

2. Pre-v5.0 Decorators: Basics & Parameters

For TypeScript versions lesser than v5.0, decorators are supported using an experimental implementation based on an early version of a JavaScript proposal from the TC39 committee — the team that evolves the JavaScript language. To enable experimental support for decorators, you must enable the experimentalDecorators compiler option either on the command line or in your tsconfig.json.

Find Typescript 5.0+ article: Typescript 5.0+ Decorators

To use decorators in Pre-v5.0 TypeScript, enable them in tsconfig.json:

{
  "target": "ES2017",
  "module": "commonjs",
  "experimentalDecorators": true,
  "emitDecoratorMetadata": true
}

Or using the command line:

tsc --target ES5 --experimentalDecorators

2.1 Types of Decorators & Their Parameters

Parameter Details

• Class Decorator: Receives the class constructor.

• Property Decorator: Receives the prototype and property name. Cannot modify descriptor directly.

• Method Decorator: Receives the prototype, method name, and descriptor (lets you override/wrap the method).

• Parameter Decorator: Receives the prototype, method name, and parameter index.

// Legacy API Examples
function MyClassDecorator(constructor: Function) {
  console.log('Class created:', constructor.name);
}

function MyPropertyDecorator(target: Object, propertyKey: string) {
  console.log('Property:', propertyKey);
}

function MyMethodDecorator(target: Object, propertyKey: string, descriptor: PropertyDescriptor) {
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    console.log(`Calling ${propertyKey}`, args);
    return original.apply(this, args);
  };
  return descriptor;
}

function MyParamDecorator(target: Object, propertyKey: string, parameterIndex: number) {
  console.log(`Parameter ${parameterIndex} in ${propertyKey}`);
}

Example Recap:

class Example {
  @MyPropertyDecorator
  someProperty: string;

  @MyMethodDecorator
  someMethod(@MyParamDecorator msg: string) {}
}

Decorators execute at compile/design time. You can modify behavior or attach annotations used by frameworks.

3. Reflection & Metadata

To read design-time types at runtime, use reflect-metadata:

1. Install: npm install reflect-metadata

2. Import once: import 'reflect-metadata';

3. Enable emitDecoratorMetadata in tsconfig.json.

// Retrieve the type of a property
Reflect.getMetadata('design:type', target, propertyKey);

Reflection lets decorators inspect types, useful for form builders, DI, or validation.

4. Angular Built-in Decorators

Angular started using decorators long before TC39 finalized the spec — and relied on TypeScript’s experimental decorators. Although under the hood Angular relies on TypeScript’s standard compiler, it has its own Angular compiler (ngc) that processes the decorators and generates code for templates, DI, etc. See The Dance of Decorated Classes: Inside the Angular Compiler. Hence, ngc can be said to be an extension TypeScript compiler which knows how to “execute” Angular decorators, applying their effects to the decorated classes at build time.

5. Writing Custom Decorators (Legacy API)

5.1 Class Decorator

function LogClass(constructor: Function) {
  console.log('Class created:', constructor.name);
}

@LogClass
class MyService {}

5.2 Method Decorator

function LogMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor {
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    console.log(`Calling ${propertyKey} with`, args);
    return original.apply(this, args);
  };
  return descriptor;
}

class Example {
  @LogMethod
  say(message: string) {
    console.log(message);
  }
}

5.3 Property Decorator

function DefaultValue(val: any) {
  return function (target: any, propertyKey: string) {
    let value = val;
    Object.defineProperty(target, propertyKey, {
      get: () => value,
      set: v => (value = v),
    });
  };
}

class Example {
  @DefaultValue("hello")
  message: string;
}

5.4 Parameter Decorator

function MyParamDecorator(target: Object, propertyKey: string, parameterIndex: number) {
  console.log(`Parameter ${parameterIndex} in method ${propertyKey}`);
}

class Example {
  someMethod(@MyParamDecorator msg: string) {}
}

6. Decorator Factories & Composition

6.1 Decorator Factories

A decorator factory is a function that returns a decorator, allowing you to pass arguments/configuration.

function LogWithPrefix(prefix: string) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor {
    const original = descriptor.value;
    descriptor.value = function (...args: any[]) {
      console.log(`${prefix}: ${propertyKey}`, args);
      return original.apply(this, args);
    };
    return descriptor;
  };
}

class Example {
  @LogWithPrefix('DEBUG')
  say(message: string) {
    console.log(message);
  }
}

6.2 Decorator Composition

Decorator composition means stacking multiple decorators on a single target. Decorators are applied bottom to top (the last decorator in code is applied first).

function Log(target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor {
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    console.log('Calling', propertyKey);
    return original.apply(this, args);
  };
  return descriptor;
}

function Cache(target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor {
  const cache = new Map<string, any>();
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    const cacheKey = JSON.stringify(args);
    if (cache.has(cacheKey)) {
      return cache.get(cacheKey);
    }
    const result = original.apply(this, args);
    cache.set(cacheKey, result);
    return result;
  };
  return descriptor;
}

class MathService {
  @Log
  @Cache
  expensiveOperation(x: number) {
    return x * x; // pretend this is slow
  }
}

7. Real-World Use Cases

7.1 Permission Check

function RequirePermission(permission: string) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor {
    const original = descriptor.value;
    descriptor.value = function (...args: any[]) {
      const svc = inject(PermissionService);
      if (!svc.hasPermission(permission)) {
        throw new Error(`Missing ${permission}`);
      }
      return original.apply(this, args);
    };
    return descriptor;
  };
}

class UserService {
  @RequirePermission('admin')
  deleteUser(id: string) {
    // Only admins can call this
  }
}

7.2 Caching

const cache = new Map<string, any>();
function CacheResult(target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor {
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    const ckey = `${propertyKey}-${JSON.stringify(args)}`;
    if (cache.has(ckey)) return cache.get(ckey);
    const res = original.apply(this, args);
    cache.set(ckey, res);
    return res;
  };
  return descriptor;
}

class DataService {
  @CacheResult
  fetchUser(id: string) {
    // Expensive API call
  }
}

7.3 Analytics on Component Init

function WithAnalytics(eventName?: string) {
  return function (constructor: any) {
    const originalInit = constructor.prototype.ngOnInit;
    constructor.prototype.ngOnInit = function () {
      const analytics = inject(AnalyticsService);
      analytics.trackEvent('Init', { name: eventName || constructor.name });
      originalInit?.apply(this);
    };
  };
}

@WithAnalytics('UserComponent')
class UserComponent {
  ngOnInit() {
    // Component initialization
  }
}

7.4 Auto-Unsubscribe

function AutoUnsubscribe(constructor: any) {
  const originalDestroy = constructor.prototype.ngOnDestroy;
  constructor.prototype.ngOnDestroy = function () {
    for (const k in this) {
      this[k]?.unsubscribe?.();
    }
    originalDestroy?.apply(this);
  };
}

@AutoUnsubscribe
class MyComponent {
  private subscription = new Subject();
  
  ngOnDestroy() {
    // Will automatically unsubscribe all subscriptions
  }
}

8. Bonus: Simple Signals & Observables

Bonus Simple Signal with fromObservable custom implementation to plug into @AutoUnsubscribe decorator.

8.1 SimpleSignal

function SimpleSignal<T>(initial: T) {
  let value = initial;
  const listeners: (() => void)[] = [];
  const signal = (() => value) as (() => T) & {
    set: (v: T) => void;
    effect: (fn: () => void) => void;
  };
  signal.set = v => { value = v; listeners.forEach(fn => fn()); };
  signal.effect = fn => { listeners.push(fn); fn(); };
  return signal;
}

8.2 fromObservable

import { Observable } from 'rxjs';
function fromObservable<T>(obs$: Observable<T>, initial: T) {
  const sig = SimpleSignal(initial);
  const sub = obs$.subscribe(val => sig.set(val));
  (sig as any).unsubscribe = () => sub.unsubscribe();
  return sig;
}

9. Code Lab: Debounce Decorator

Objective: Create a @Debounce method decorator that delays method execution.

function Debounce(ms: number) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor {
        console.log("Inside the debounce decorator");
        const original = descriptor.value;
      let timeoutId: number;
      
      descriptor.value = function (...args: any[]) {
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
          original.apply(this, args);
        }, ms);
      };
      
      return descriptor;
    };
  }

  class SearchComponent {
    @Debounce(300)
    onSearch(query: string) {
      // This will only execute after 300ms of no calls
      console.log('I waited for 300 ms to do nothing.... arghhhh!');
    }
  }

Usage:

  // Test the debounce functionality
  const searchComponent = new SearchComponent();
  
  console.log('Calling onSearch multiple times quickly...');
  searchComponent.onSearch('test1');
  searchComponent.onSearch('test2');
  searchComponent.onSearch('test3');
  
  // The original method will only execute once after 300ms
  // because the debounce decorator delays execution and cancels previous calls

10. Migration to New API

Key Differences:

Migration Example:

Legacy (Current):

function LogMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    console.log(`Calling ${propertyKey}`, args);
    return original.apply(this, args);
  };
  return descriptor;
}

New API (Future):

function LogMethod<T extends object>(
  target: undefined,
  context: ClassMethodDecoratorContext<T, (this: T, ...args: any[]) => any>
): void {
  const methodName = context.name;
  context.addInitializer(function (this: T) {
    const originalMethod = this[methodName as keyof T] as (this: T, ...args: any[]) => any;
    (this as any)[methodName] = function (this: T, ...args: any[]) {
      console.log(`Calling ${String(methodName)}`, args);
      return originalMethod.call(this, ...args);
    };
  });
}

11. Best Practices & Summary

• Keep decorators small and single-purpose

• Prefer decorator factories for configurability

• Document execution order if it matters

• Understand evaluation and application order: decorators are applied bottom-to-top

• Use reflection for advanced scenarios (type inspection, DI, validation)

• Leverage composition to separate concerns and reuse logic

• Consider upgrading to new API for TypeScript 5.0+ projects

• Test thoroughly when migrating between APIs

🎉 You now have a complete advanced reference for TypeScript legacy decorators, including real-world use cases, composition, and migration guidance to the new API. Review remarks are always welcome.

Happy decorating.

This article will guide you through building a modern, AI-powered e-commerce application using Angular for the front end and leveraging the capabilities of Google's Firebase AI Logic (formerly Vertex AI in Firebase). We will explore how to implement intelligent features by referencing code snippets from the "Bytewise" e-commerce application, a practical example I created, available on GitHub.

The Inevitable Rise of AI in E-commerce

Initially, e-commerce platforms focused on providing a convenient way to browse and purchase products. As the market matured, the focus shifted towards enhancing the user experience through features like customer reviews, wishlists, and basic recommendation engines. However, with the explosion of online stores and product variety, a new set of challenges emerged. Shoppers became overwhelmed with choices, and businesses struggled to differentiate themselves.

This is where AI steps in. By harnessing the power of machine learning and large language models (LLMs), e-commerce businesses can now:

• Automate Customer Support: AI-powered chatbots can handle a vast range of customer inquiries 24/7, from order tracking to product questions, freeing up human agents to tackle more complex issues.

• Personalize Shopping Experiences: AI algorithms can analyze user behavior, purchase history, and even real-time interactions to provide highly personalized product recommendations, search results, and marketing content.

• Optimize Inventory and Pricing: Predictive analytics can forecast demand, helping businesses manage their stock levels more effectively and implement dynamic pricing strategies to maximize revenue.

• Streamline Product Discovery: AI can power intelligent search functionalities that understand natural language queries, making it easier for customers to find exactly what they are looking for.

Introducing Firebase AI Logic: The Brains of Your E-commerce App

Firebase AI Logic is a powerful suite of tools that allows developers to easily integrate Google's cutting-edge generative AI models, like Gemini, directly into their web and mobile applications. It acts as a bridge between your application and powerful AI capabilities, handling the complexities of model deployment and scaling.

Firebase has evolved from "Vertex AI in Firebase" to the more robust "Firebase AI Logic," offering greater flexibility in building AI features. Developers can now use either the free Gemini Developer API or the Vertex AI Gemini API, and importantly, there's no need to include your Gemini API key directly in your app's code.

• Gemini Developer API—billing is optional (available on the no-cost Spark plan)

• Vertex AI Gemini API—billing is required (requires the pay-as-you-go Blaze plan)

Building an AI-Powered E-commerce App with Angular and Firebase

Let's dive into the practical aspects of building our AI-powered e-commerce application, "Bytewise." The application is built with Angular, a popular framework for creating dynamic single-page applications, and utilizes Firebase for its backend services, including Firebase AI Logic for its intelligent features.

You can find the complete source code for the Bytewise application on GitHub: https://github.com/waynegakuo/bytewise

About Bytewise

ByteWise is a fictional e-commerce platform that showcases electronic products with an integrated AI shopping assistant. The application features:

• Product catalog with detailed product information

• AI assistant that can answer questions about products

• Voice recognition for hands-free interaction with the AI assistant

• Shopping cart functionality

• Responsive UI with modern design

Screenshot: ByteWise app in action

Setting Up the Project🚀

This article assumes familiarity with Angular and Firebase setup. For setup instructions, please refer to the "Setting Up Locally" section before cloning the project.

Alternatively, you can open the ByteWise project on Firebase Studio, which will provide you with a web-based IDE with the requirements provisioned, and follow along.

Firebase Project and Firebase AI Logic Setup 🔥

Next, you'll need a Firebase project with a web application configured. You will also need to enable Firebase AI Logic on your Firebase project.

Follow the directions in Step 1 to create a project and a web app. You do not need to add any SDK code snippets during this step, as this example project already includes them.

After creating your Firebase project, go to the Firebase AI Logic page in the Firebase console. Click "Get Started" and select "Get started with this API" for the Gemini Developer API. This API is preferable as it avoids the need to provide billing details.

Register your web app by clicking on the web icon as shown in the screenshot below:

Leave the Firebase Hosting checkbox unchecked. After obtaining your Firebase credentials (firebaseConfig), copy the entire contents; you'll need them in the next step.

Back in our codebase, in the environment.ts file, paste the contents of the Firebase configuration details into the firebaseConfig object.

// src/environments/environment.ts

export const environment = {
  production: false,
  firebaseConfig: {
    apiKey: "<your-api-key>",
    authDomain: "<your-app-domain>",
    projectId: "<your-project-id>",
    storageBucket: "<your-storage-bucket-id>",
    messagingSenderId: "<your-message-sender-id>",
    appId: "<your-app-id>",
    measurementId: "<your-measurement-id>"
  },
};

Install dependencies:

npm install

Running the Application 🏃‍♂️

With the configuration complete, you can now start the development server:

ng serve

This command will build your Angular application and start a local development server. You can then access the application in your web browser at http://localhost:4200

Core Architecture

Product State Management with Signals

The foundation of our system uses Angular's signal-based state management:

// src/app/services/product.service.ts

@Injectable({
  providedIn: 'root'
})
export class ProductService {
  private readonly products = signal<Product[]>([]);
  private readonly cart = signal<Product[]>([]);
  
  readonly cartCount = computed(() => this.cart().length);
  readonly totalPrice = computed(() => 
    this.cart().reduce((sum, item) => sum + item.price, 0)
  );

  constructor() {
    // Initialize with default products
    this.products.set([
      { id: 1, name: 'Laptop', price: 85000 },
      { id: 2, name: 'Smartphone', price: 35000 }
    ]);
  }

  getProducts() {
    return this.products();
  }

  addToCart(product: Product) {
    this.cart.update(current => [...current, product]);
  }

  clearCart() {
    this.cart.set([]);
  }
}

AI Service

One of the most common and effective uses of AI in e-commerce is a customer support chatbot. In the Bytewise application, we have a AiService that handles the interaction with the Firebase AI Logic.

// src/app/services/ai.service.ts

@Injectable({
  providedIn: 'root'
})
export class AiService {
  private readonly productService = inject(ProductService);
  private readonly model: GenerativeModel;
  private readonly chat: ChatSession;

  ...
}

This service utilizes Angular's dependency injection system to maintain a clean, modular architecture. The service manages both the AI model and chat session, creating a seamless interface between user interactions and AI responses.

AI Configuration and Tool Integration

The system defines specific e-commerce operations through a structured tool set:

// src/app/services/ai.service.ts

const productsToolSet: FunctionDeclarationsTool = {
  functionDeclarations: [
    {
      name: "getTotalNumberOfProducts",
      description: "Get the total number of products available in the store.",
    },
    {
      name: "getProducts",
      description: "Get an array of the products with the name and price of each product.",
    }
    // Additional function declarations...
  ]
};

This tool set enables the AI to perform specific actions within the e-commerce system, from checking inventory to managing shopping carts.

Strong Type Safety with Schema Definitions

Product data integrity is maintained through robust schema definitions:

// src/app/services/ai.service.ts

...

Schema.object({
  properties: {
    productsToAdd: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string({
            description: "The name of the product.",
          }),
          price: Schema.number({
            description: "The numerical price of the product.",
          }),
        },
        required: ["name", "price"],
      }),
    }),
  },
})

...

This schema ensures that all product-related operations maintain data consistency and type safety.

Gemini Developer API Setup and System Instructions

The integration with Google's Gemini AI is configured with specific business rules:

// src/app/services/ai.service.ts

...

const geminiAI = getAI(this.firebaseApp, {backend: new GoogleAIBackend()});
const systemInstruction =
  "Welcome to ByteWise. You are a superstar agent for this ecommerce store..." ;

this.model = getGenerativeModel(geminiAI , {
  model: "gemini-2.0-flash",
  systemInstruction: systemInstruction,
  tools: [productsToolSet],
});

...

The code initializes a Gemini AI-powered chatbot for the e-commerce store, which will interact with the inventory system and shopping cart, and is equipped with tools to perform various shopping-related functions.

The systemInstruction property is crucial as it helps the AI model understand its context and maintain consistent formatting when interacting with users about products and prices in the ByteWise ecommerce store.

AI Interaction Processing

The system handles AI interactions through a sophisticated message processing system:

// src/app/services/ai.service.ts

...

async askAgent(userPrompt: string) {
  let result = await this.chat.sendMessage(userPrompt);
  const functionCalls = result.response.functionCalls();

  if(functionCalls && functionCalls.length > 0) {
    for (const functionCall of functionCalls) {
      switch (functionCall.name) {
        case "getTotalNumberOfProducts": {
          const functionResult = this.getTotalNumberOfProducts();
          // Process response
          break;
        }
        // Additional case handling...
      }
    }
  }
  return result.response.text();
}

...

The askAgent function takes a user's prompt (their question or message) as input, sends it to the Gemini model via Firebase AI Logic, and returns the model's generated text response.

Think of it as a smart assistant for an e-commerce store that can understand user requests and perform actions. Here's how it works:

1. Taking User Input:

• When a user types something (like "How many products do you have?" or "Add this to my cart"), the method takes this message as a userPrompt

• It sends this message to an AI chat system

2. Checking for Actions:

• The AI analyzes the message and decides if it needs to perform any specific actions (called "function calls")

• For example, if you ask "How many products are there?", it will need to check the actual product count

3. Handling Different Actions: The method can handle four main types of actions:

• getTotalNumberOfProducts: Counts all products in the store

• getProducts: Gets the list of all available products

• clearCart: Empties the shopping cart

• addToCart: Adds specific products to the cart

4. Completing the Conversation:

• After performing any necessary actions, it sends the results back to the AI

• The AI then forms a natural response to the user

• This response is returned to be shown to the user

It's like having a helpful store assistant who can both answer questions and perform actions for you!

Service Integration in Components

Bringing it all together in the user interface:

// src/app/components/agent-window.component.ts


@Component({
  selector: 'app-agent-window',
  ...
})
export class AgentWindowComponent {
  private readonly aiService = inject(AiService);
  readonly productService = inject(ProductService);
  ....

  constructor() {
    this.productList.set(this.productService.getProducts());
    ...
  }

  async sendMessage(): Promise<void> {
    if (this.userInput.trim() === '') return;

    // Add user message
    this.messageHistory.update((history) =>
      [...history, { text: this.userInput, isUser: true }]
    );

    // Clear input
    const userQuestion = this.userInput;
    this.userInput = '';

   ...

    try {
      const response = await this.aiService.askAgent(userQuestion);
      this.messageHistory.update((history) => [
        ...history,
        { isUser: false, text: response }
      ]);
    } finally {
      // Set thinking state to false regardless of success or failure
      this.isThinking.set(false);
    }
  }

  ...
}

This component serves as the main interface for user-AI interaction in your e-commerce platform, providing a clean and intuitive chat experience while maintaining a reactive and performant implementation using Angular’s signals.

Conclusion

The integration of AI is no longer a futuristic concept in e-commerce; it's a present-day necessity for creating engaging, efficient, and personalized online shopping experiences. By combining the power of a versatile front-end framework like Angular with the accessible and powerful AI capabilities of Firebase AI Logic, developers can build the next generation of e-commerce applications.

The Bytewise example provides a solid foundation for understanding the practical implementation of these concepts. As AI models continue to evolve and become more sophisticated, the possibilities for innovation in e-commerce are boundless. The journey to a truly intelligent online store starts with embracing these powerful tools and reimagining what's possible in the world of online retail.

There are a number of ways to solve this issue other than training your own AI models. One of the options is Retrieval-Augmented Generation (RAG), where we ground the LLMs based on external data to improve the accuracy and relevance of the responses.

The other option is Function Calling, which is the subject of today’s article. Function calling—known as tool calling in Genkit—involves giving AI Models a structured way to interact with your application/system or external data sources (APIs) to accomplish various tasks and ensuring it has up-to-date data. The AI Model will then call those functions we provide to accomplish various tasks, such as to fetch user data, create a ticket for the user, and so on.

To demonstrate this, we will be building a simple customer support agent that will answer questions from customers, and the AI Model will use the tools we provide to determine which tools it needs to call to accomplish the customer’s goal.

Defining Genkit Tools

In Genkit, tools are special functions that contain information about what they are meant to accomplish and the means to accomplish the intended task — a function.

A tool in Genkit is defined using the defineTool method which accepts two arguments: a config object and a function.

ai.defineTool(
  {
    name: 'toolName',
    description: 'Tool Description',
  },
  async ({ customerId }) => {
    // implementation to fetch customer details
  },
);

Please Note:

The ai instance is created by calling genkit function, passing in a number of configurations such as plugins for the AI Model you want to use, and the default model. For more information, checkout the Genkit documentation, here.

import { gemini20Flash, googleAI } from '@genkit-ai/googleai';
import { genkit } from 'genkit';

const ai = genkit({
  plugins: [googleAI()],
  model: gemini20Flash,
});

A config is where we describe what the tool does; we give a descriptive name and a description that describes the tool's intended purpose. We can also include input and output JSON schemas (supports zod out of the box) among other options. Only the description and name are required.

The second argument is the function where we implement the tool’s objective. For instance, inside the function, we can make a DB call, an API call or any other deterministic operation, based on the tool’s intended objective.

For instance, in our case, we might want to define a tool to fetch customer information, given a customer ID. In this case, we would define a GetCustomerDetails tool that looks up the customer details from our database.

Please note we are providing an input and output schema to ensure data is returned in a very specific format, all the time, and we will ensure we provide a good description of our tool.

const getCustomerDetailsTool = ai.defineTool(
  {
    name: 'GetCustomerDetails',
    description: 'Fetches details of a customer by ID',
    inputSchema: z.object({
      customerId: z.string().describe('The ID of the customer to fetch details for'),
    }),
    outputSchema: customerSchema,
  },
  async ({ customerId }) => {
    // This could be a database call or an API request in a real application.
    const customer = customers.find((customer) => customer.id === customerId);
    if (!customer) {
      throw new Error(`Customer with ID ${customerId} not found`);
    }
    return customer;
  },
);

Now that we have created our first tool, we will need to pass it to the AI Model so it can use it, if need be, based on the customer’s question. In Genkit, there are several ways of achieving this, depending on whether we are using a flow, a prompt, or we are invoking the generate method directly inside the function.

When calling the generate method, passing the tool, in the tools’ options, alongside the prompt as shown below:

const { text } = await ai.generate({
  prompt: `
  You are an eCommerce Customer Service AI.
  You can answer questions about customers and their orders.
  You have access to the following tools:
  - Get Customer Details: Fetches details of a customer by ID.
  - Get Customer Orders: Fetches orders for a specific customer, by customer ID.
  Use the tools to answer questions about customers and their orders.
  If you need to fetch customer details, use the Get Customer Details tool.
  If you need to fetch customer orders, use the Get Customer Orders tool.
  If you cannot answer a question, respond with "I don't know" or "I cannot answer that question".

  When answering questions, use the following format:
  - If the question is about customer details, provide the customer's name, email, and phone number.
  - If the question is about customer orders, provide the number of orders placed and details of the most recent order.
  - If the question is about a product, provide the product name, price, and description.

  Use all tools to fetch the necessary information, do not return IDs, instead return the relevant details the user is interested in.

  Example questions:
  - What is the email address of customer with ID 1?
  - How many orders has customer with ID 2 placed?
  
  The customer id is ${customerID} and the question is: ${question}
  `,
  tools: [getCustomerDetailsTool],
  toolChoice: 'auto',
});

As you can see, our prompt is rather detailed, as we have to clearly instruct the AI Model to behave exactly the way we want, and reduce instances of it hallucinating. In cases where it has no answer, we want the AI model to say it doesn’t know, instead of hallucinating.

We can put the above generate method call in a function, and call it as shown below. On top of that, we are passing our tool — getCustomerDetailsTool — in the tools section.

async function run() {
  const { text } = await ai.generate(...);
  // log our response
  console.log(text);
}

run();

However, running the above can be very difficult, as you need to pass in the inputs in the correct format and almost impossible to debug. This is where Genkit Developer UI comes in.

Genkit Developer UI

Genkit provides a developer UI where you can view, invoke and test your flows, prompts, tools, among others, in a very user-friendly UI, which enhances the developer experience.

To launch the Genkit Developer UI, you can do so by running the following command:

npx genkit start -- npx tsx --watch index.ts

In the above command, genkit is the genkit cli, and tsx is an NPM package for executing TypeScript files, without needing to transpile to Javascript first. index.ts is the file which contains our code, and the entry file of our project.

Since we have already defined our tool, running the above command, we should be able to see it in the UI and even interact with it, as shown below:

Defining a Genkit Flow

For our case, we are going to switch to a flow. We will define a flow using the defineFlow method, which takes two arguments — a config object and a function to be executed when the flow is called.

For the flow config object, we will set the name of the flow, the input and output schema, keeping things simple for now. In the function, we will call the generate method, just like we previously did. We will return the text, so we can see the response of the AI Model in the UI.

const assistant = ai.defineFlow(
  {
    name: 'eCommerceCustomerServiceAI',
    inputSchema: z.object({
      customerID: z.string().describe('The ID of the customer to fetch details for'),
      prompt: z.string().describe('The question or request for customer service'),
    }),
    outputSchema: z.string().describe('The response from the AI assistant'),
  },
  async ({ customerID, prompt }) => {
    const { text } = await ai.generate({
      prompt: `
      You are an eCommerce Customer Service AI.
      You can answer questions about customers and their orders.
      You have access to the following tools:
      - Get Customer Details: Fetches details of a customer by ID.
      - Get Customer Orders: Fetches orders for a specific customer, by customer ID.
      Use the tools to answer questions about customers and their orders.
      If you need to fetch customer details, use the Get Customer Details tool.
      If you need to fetch customer orders, use the Get Customer Orders tool.
      If you cannot answer a question, respond with "I don't know" or "I cannot answer that question".

      When answering questions, use the following format:
      - If the question is about customer details, provide the customer's name, email, and phone number.
      - If the question is about customer orders, provide the number of orders placed and details of the most recent order.
      - If the question is about a product, provide the product name, price, and description.

      Use all tools to fetch the necessary information, do not return IDs, instead return the relevant details the user is interested in.
  
      Example questions:
      - What is the email address of customer with ID 1?
      - How many orders has customer with ID 2 placed?
      
      The customer id is ${customerID} and the question is: ${prompt}
      `,
      tools: [getCustomerDetailsTool],
      toolChoice: 'auto',
    });

    return text;
  },
);

Our input schema will accept a customer ID and a question from the customer. The customer ID would likely come from the user session, while the question would be what the prompt the user entered in the chat input or system-generated, doesn't matter that much for this article.

Next, we can use the developer UI to test the flow and see if we can get some user details from our database (I know it’s fake).

You may be wondering, how do we know it’s working? The developer UI provides a stack trace to show you what exactly when during the execution, as shown below:

As you can see, this can be very helpful when troubleshooting your Genkit application and trying to figure out where things are going wrong. It will show you all the calls it made to the tools, including the inputs and outputs of each step.

Finalising the Agent

As it currently stands, no customer will be asking about their names, but hopefully, you get the idea. The customer would likely want to know the status of their orders, among other things. We will add more tools for getting order information and product information, following the template we have seen earlier, as shown below:

const getCustomerOrdersTool = ai.defineTool(
  {
    name: 'GetCustomerOrders',
    description: 'Fetches orders for a specific customer, by customer ID',
    inputSchema: z.object({
      customerId: z.string().describe('The ID of the customer to fetch orders for'),
    }),
    outputSchema: z.array(orderSchema),
  },
  async ({ customerId }) => {
    return orders.filter((order) => order.customerId === customerId);
  },
);

const getProductDetailsTool = ai.defineTool(
  {
    name: 'GetProductDetails',
    description: 'Fetches product details by product ID',
    inputSchema: z.object({
      productId: z.string().describe('The ID of the product to fetch details for'),
    }),
    outputSchema: productSchema,
  },
  async ({ productId }) => {
    const product = products.find((product) => product.id === productId);
    if (!product) {
      throw new Error(`Product with ID ${productId} not found`);
    }
    return product;
  },
);

And then, we will add the above tools to the tools section, in the generate method, next to the one we already have, as shown below:

const assistant = ai.defineFlow(
  {
    // ... nothing changes here
  },
  async ({ customerID, prompt }) => {
    const { text } = await ai.generate({
      prompt: `...`,
      tools: [
        getCustomerDetailsTool, 
        // we add the tools here
        getCustomerOrdersTool, 
        getProductDetailsTool
      ],
    });

    return text;
  },
);

And finally, we can use the Genkit Developer UI to test whether our flow and tools work.

As you can see, the AI model — in our case, Gemini — figures out the status of the customers’ orders and associates them with products by utilising the different tools we provided. While the prompt can be improved to allow the customer not to be very specific, and still accomplish the same goals, hopefully, you get the idea of how we can give LLMs the ability to interact with our systems to accomplish different goals.

If you are interested, you can find the above source code here.

Conclussion

In this post, we discussed function calling that allows you to give AI models access to your applications and system, so that they can get things done. We also looked at the Genkit Developer UI, for the purpose of testing and debugging our flows, tools and applications we are building on top of AI models.

I hope this article gave you ideas on how you can use Genkit to build AI agents to help accomplish various tasks on behalf of customers, and if you have any questions, please feel free to put them in the comment section below.

Until next time, keep on learning.

Ready to Move From AI Hype to Real-World Results?

At Unstacked Labs, we specialise in building practical AI agents, like the one in this article, that automate complex workflows and solve real business problems.

Let's discuss your company needs

// Angular Signals

const count = signal(0);
// then call the Signal like a function - reads the value.
console.log('The count is: ' + count());

// invoke Object function
count.set(3);

And that is when i came across the idea Javascript Callable Functions and also reminded me of the fact that in JavaScript all functions are object methods.

Our exercise works based on the premise that a callable object behaves as both as an object and a function. You can access it and assign its properties values obj.bar = value, call its methods obj.foo(), but also call the object directly obj(), as if it were a function.

In order for all these things to make sense we also refer to the classical constructor pattern used in object-oriented programming languages. The constructor pattern is a style used to initialise a newly created object once memory has been allocated for it. In our case here, we’re interested in object constructors.

Object constructors will create specific types of objects. The process of creating these objects can accept arguments through a constructor to set the values of member properties and methods when the object is first created. Once the object is ready we can manipulate properties via setters, access them via getters and call object methods.

JavaScript doesn’t support the concept of classes, but it does support special constructor functions that work with objects. By simply prefixing a call to a constructor function with the keyword new, we can tell JavaScript we would like the function to behave like a constructor and instantiate a new object with the members defined by that function. Inside a constructor, the keyword this references the new object that’s being created.

I will assume that going on forward you have a good understanding of the constructor pattern (plus you have taken some time to read about it if this is new) as this will form a foundational concept for the idea behind the custom simple signal we are about to build.

The idea we are pursuing here does not imply this is how Angular Signals code looks like, but rather it is exploring an idea in an attempt to understand possible patterns and how Angular Signals concept works.

Alright, lets ride this wave…

First we start at the very basic, how do achieve this in typescript…

obj = new ObjClass(); 
this.obj() // this call runs a certain function

In TypeScript, to achieve this behavior where calling this.obj() runs a certain function, you can make use of a getter or explicitly define a method in your class.

Here’s how you can do it:

1. Using a Getter

You can define a getter in your class that executes a specific function when accessed:

class ObjClass {
  private someMethod(): void {
    console.log("Function is called!");
  }

  get obj(): () => void {
    return this.someMethod.bind(this);
  }
}

const instance = new ObjClass();
instance.obj(); // This will log "Function is called!"

2. Defining a Method

Alternatively, you can directly define a method in the class instead of using a getter.

class ObjClass {
  obj(): void {
    console.log("Function is called!");
  }
}

const instance = new ObjClass();
instance.obj(); // This will log "Function is called!"

3. Using a Property with an Arrow Function

If you want more control or don’t need to bind this manually, you can assign an arrow function to a property:

class ObjClass {
  obj = () => {
    console.log("Function is called!");
  };
}

const instance = new ObjClass();
instance.obj(); // This will log "Function is called!"

Key Differences

• Getter: Method to be accessed as a property but still invoke a function.

• Method: Conventional way of defining functions in a class.

• Arrow Function Property: Ensure this is always bound to the class instance.

Lets move a notch higher, to how do we call the instance of a class like a function.

class ObjClass {
  obj = () => {
    console.log("Function is called!");
  };
}

const instance = new ObjClass();
instance(); // This will log "Function is called!"

Using a Function Constructor

You can define the class in a way that the constructor returns a callable function.

class ObjClass {
  obj = () => {
    console.log("Function is called!");
  };

  constructor() {
    const callable = () => this.obj();
    return Object.assign(callable, this); // Combine the function and the class instance
  }
}

const instance = new ObjClass() as unknown as () => void;
instance(); // Logs "Function is called!"

The constructor creates a callable function (callable) that calls the obj method. Object.assign merges the class properties and methods into the function, so instance behaves like both a function and an instance of the class.

Angular Signals

Angular signals were introduced as part of Angular’s reactive system, starting with Angular 16. Signals provide a reactive primitive for managing and tracking state changes, similar to reactive systems in frameworks like SolidJS. They allow you to manage data reactivity without relying heavily on observables or subscriptions.

Key Features of Angular Signals

1. Declarative Reactivity:
   Signals automatically track dependencies and update the UI when values change.

2. Synchronous and Predictable:
   Unlike observables, signals are synchronous and provide direct access to the current value without requiring .subscribe().

3. Track Dependencies Automatically:
   Signals automatically capture dependencies during execution, which simplifies state management.

4. Composable:
   You can create derived signals and combine signals to manage more complex state transformations.

In Angular a signal can created like so:

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

const count = signal(0);

console.log(count()); // Get the current value: 0
count.set(5);         // Update the value
console.log(count()); // Output: 5

For more on signals: Angular Signal Docs

Minimal Custom Signal Implementation using a Class

Lets create an overly simplified version of Angular signals using just a class in TypeScript. The idea is to have reactive primitives that can store a value, update it, and notify listeners (like effects).

class SimpleSignal<T> {
  private value: T;
  private listeners: (() => void)[] = [];

  constructor(initialValue: T) {
    this.value = initialValue;
  }

  // Getter for the current value
  get(): T {
    return this.value;
  }

  // Setter for the value, notifying all listeners
  set(newValue: T): void {
    this.value = newValue;
    this.notify();
  }

  // Subscribe to changes
  effect(listener: () => void): void {
    this.listeners.push(listener);
    // Run the effect once initially
    listener();
  }

  // Notify all listeners of the value change
  private notify(): void {
    for (const listener of this.listeners) {
      listener();
    }
  }
}

Usage Examples:

1. Create SimpleSignal

const count = new SimpleSignal(0);

// Access the current value
console.log(count.get()); // Output: 0

2. Update SimpleSignal

count.set(5);
console.log(count.get()); // Output: 5

3. Create an Effect

count.effect(() => {
  console.log(`Count changed to: ${count.get()}`);
});

count.set(10); // Logs: "Count changed to: 10"
count.set(20); // Logs: "Count changed to: 20"

Minimal Custom Computed Signal Implementation using a Class

class SimpleComputedSignal<T> {
  private computeFn: () => T;
  private listeners: (() => void)[] = [];
  private cachedValue!: T;

  constructor(computeFn: () => T) {
    this.computeFn = computeFn;
    this.cachedValue = this.computeFn();
  }

  get(): T {
    return this.cachedValue;
  }

  update(): void {
    this.cachedValue = this.computeFn();
    this.notify();
  }

  effect(listener: () => void): void {
    this.listeners.push(listener);
    listener();
  }

  private notify(): void {
    for (const listener of this.listeners) {
      listener();
    }
  }
}

// Usage:
const baseCount = new SimpleSignal(2);
const doubleCount = new SimpleComputedSignal(() => baseCount.get() * 2);

doubleCount.effect(() => {
  console.log(`Double Count: ${doubleCount.get()}`);
});

baseCount.set(3); // Logs: "Double Count: 6"

Minimal Custom Signal Implementation using a Function

Now that we’ve seen how we can do this using a class, let’s see how we can this using function… hint: remember that functions are objects in Javascript.

function SimpleSignal<T>(initialValue: T) {
  let value = initialValue;
  const listeners: (() => void)[] = [];

  // The callable signal function
  const signal = (() => value) as (() => T) & {
    set: (newValue: T) => void;
    effect: (listener: () => void) => void;
  };

  // Add the `set` method to update the value and notify listeners
  signal.set = (newValue: T) => {
    value = newValue;
    listeners.forEach((listener) => listener());
  };

  // Add the `effect` method to register listeners
  signal.effect = (listener: () => void) => {
    listeners.push(listener);
    // Run the effect immediately
    listener();
  };

  return signal;
}

Usage:

// create simple signal
const baseCount = SimpleSignal(0);

// get the value
console.log(baseCount()); // Output: 0

// update value
baseCount.set(5);
console.log(baseCount()); // Output: 5

// add an effect
baseCount.effect(() => {
  console.log(`Base count changed to: ${baseCount()}`);
});

baseCount.set(10); // Logs: "Base count changed to: 10"
baseCount.set(20); // Logs: "Base count changed to: 20"

So what have we here:
SimpleSignal Function:

1. Returns a callable function (signal) that holds the current value.

2. The signal function is enhanced with additional properties: set and effect.

signal():

1. Acts as a getter for the signal value.

2. When invoked, it simply returns the current value.

signal.set(newValue):

1. Updates the signal’s value and notifies all registered listeners.

signal.effect(listener):

1. Registers a listener that gets called whenever the signal value changes.

Minimal Custom Computed Signal Implementation using a Function

Lets use this approach to make computed signals as well.

function SimpleComputedSignal<T>(computeFn: () => T) {
  const signal = (() => computeFn()) as (() => T)

  const listeners: (() => void)[] = [];

  signal.effect = (listener: () => void) => {
    listeners.push(listener);
    listener();
  };

  const notify = () => {
    listeners.forEach((listener) => listener());
  };

  // Automatically track dependencies and notify listeners
  const originalCompute = computeFn;
  computeFn = () => {
    notify();
    return originalCompute();
  };

  return signal;
}

const baseCount = UpdatedSimpleSignal(2);
const doubleCount = UpdatedSimpleComputedSignal(() => baseCount() * 2);

const baseCount = UpdatedSimpleSignal(2);
const doubleCount = UpdatedSimpleComputedSignal(() => baseCount() * 2);

console.log(`Double count: ${doubleCount()}`);

baseCount.set(4); 

console.log(`Double count: ${doubleCount()}`); // Logs: "Double count: 8"

baseCount.set(8);
console.log(`Double count: ${doubleCount()}`); // Logs: "Double count: 16

baseCount.set(16);
console.log(`Double count: ${doubleCount()}`); // Logs: "Double count: 32

Github link: Simple Signal Repo

More reading:

Creating Callable Objects in JavaScript
var obj = new CallableObject(); obj(args);medium.com

JavaScript Design Patterns
Constructor Patternmedium.com

Callable values
(Ad, please don't block.) 27.1 Kinds of functions 27.2 Ordinary functions 27.2.1 Named function expressions (advanced)…exploringjs.com

Let’s take the following simple function that gets items from the database - Dynamodb. Using the AWS SDK (v3), this function would look something like this:

const client = new DynamoDBClient();
const docClient = DynamoDBDocumentClient.from(client);

export async function getToDo(id: string) {
  const res = await docClient.send(
    new GetCommand({
      TableName: 'Todos',
      Key: {
        id: id,
      },
    }),
  );
  // Avoid assertions, whenever possible
  return res.Item as ExchangeRateDBObject;
}

The above function will use the AWS SDK to call the Dynamodb API and retrieve a to-do item with a given ID from the database. As long as you don’t have permission issues, it works.

Share

On the other hand, writing unit tests for it might be tricky, as the test would require access to an actual AWS Account or a local version of Dynamodb, each with its own set of challenges.

There are several ways to handle this, which I won’t go into in this article, but one of my favourites is mocking the Dynamodb SDK (Or any other SDK). The problem I generally find with mocks is that developers do not check whether the mocked function was called correctly.

Jest Spies

To give you an example, when we mock out our Document Client above, we not only need to respond with the correct return signature—for instance, in our case, we only care about the Item property—but we also need to ensure that we passed in the correct information to the client.

In our case, the table name and the key must be correct; otherwise, if incorrect, our function would not work in the real world.

This is where Jest Spies come in. The Jest spy method allows us to monitor the behaviour of other functions without changing the underlying code for the purpose of testing. With spies, we can observe a few things, such as the times it was called and the parameters or inputs it was called with.

So, for instance, to test the above function, we would need to spy on docClient send method, returning the necessary response for our function to use, as shown below:

it('Should pass the correct Key to the DB', async () => {
  const spyOnDB = jest.spyOn(docClient, 'send').mockReturnValue({
    Item: mockToDo,
  } as any);

  await getToDo('123');
});

Now, if we run the above test, it will succeed using the mock test, as shown below.

But if you recall correctly, we have mocked (using the jest.spyOn method) out our SDK call, but we aren’t doing anything to verify that we are calling our SDK correctly, which was one of my gripes with mocks in the first place.

We can now use a number of methods from the Jest matchers, such as toHaveBeenCalled and toHaveBeenCalledWith to ensure that our SDK/ function we are spying on was called a number of times, once in our case and was with the correct inputs/parameters.

expect(spyOnDB).toHaveBeenCalled();

The above matcher checks that our SDK was called; it doesn’t check whether it was called once or twice. If we wanted to be specific, Jest provides a different matcher that you can use to ensure the number of calls - toHaveBeenCalledTimes method.

expect(spyOnDB).toHaveBeenCalledTimes(1);

If our SDK is called more than once or not called at all, the test will fail. Neat, right?

Next, we can check whether the SDK passed the correct parameters. For that, we will use the toHaveBeenCalledWith method to check whether the correct inputs were passed to our AWS SDK.

expect(spyOnDB).toHaveBeenCalledWith({
    TableName: 'Todos',
    Key: {
      id: '123',
    },
});

Unfortunately, while we care about the above input, the GetCommand class transforms our input and appends some metadata, which we don’t care about for our test, but is still important. Due to that, the above test will fail.

As seen above, our SDK input contains much more information than what we are checking, with the information we need nested somewhere in there. This is where Jest comes to the rescue with another feature—asymmetric Matchers.

Asymmetric Matchers in Jest

Asymmetric Matchers are magical in Jest, as they allow us flexibility when matching and asserting results in Jest, such as partial matching, as we want.

For instance, let’s say we have a random ID generator that’s prefixed, e.g., user_UUID_STRING. We could mock out the ID generator function to return a predetermined string—deterministic behaviour is important for testing. Another option is to use asymmetric matchers to check whether the returned ID contains our prefix, as shown below:

expect(res).toEqual({
    ...USER_DETAILS,
    // Ensure the id is a string and starts with "user_"
    id: expect.stringContaining("user_"),
    // Or ensure the date is in the correct format
    updatedAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/),
});

As you can see, we are ensuring that the ID starts with the user_ prefix and the updatedAt date is of the correct matchers.

Circling back to our previous example, we now know that we need to ensure that the object passed to our SDK spy contains the following object, as we don’t care about the metadata and other details that the GetCommand appends.

{
    input: {
      TableName: 'Todos',
      Key: {
        id: '123',
      },
    },
}

Jest provides an asymmetric matcher for just this situation - expect.objectContaining. And this will check the results to see whether it contains the object we pass in, instead of strictly checking it, as shown below:

expect(spyOnDB).toHaveBeenCalledWith(
    expect.objectContaining({
      input: expect.objectContaining({
        TableName: 'Todos',
        Key: {
          id: '123',
        },
      }),
    }),
);

In layman’s terms, we are doing a partial check, and as long as the fields that we specify exist within the results, our test will parse, as shown below:

On top of that, Jest provides a good number of asymmetric matchers that you can use to make your life a little bit easier.

Just keep in mind that you need to ensure you are testing the most critical aspect of your code, and don’t use this as a shortcut by overusing matchers such as expect.anything or expect.any, which can literally match any string.

You can learn more about Asymmetric Matchers here.

Conclusion

In conclusion, unit testing when dealing with third-party APIS can be challenging, especially when it comes to ensuring that mocks accurately reflect the interactions with the real SDKS.

By leveraging both Jest Spies and Asymmetric Matchers, developers can create more robust, reliable and more effective tests that not only verify the functionality of their own functions but also confirm that the SDKS are being called correctly with the right parameters.

This enhances the reliability of your tests and helps maintain the integrity of your application's behaviour. Remember, while mocking provides a useful abstraction layer, focusing on meaningful assertions that capture the critical aspects of your application when using asymmetric matchers is essential, making sure that critical elements are what they should be while ignoring everything else.

By doing so, you'll be well-equipped to navigate the complexities of unit testing in a world full of dependencies. Happy testing!

Share

But as your project grows, this can start to have negative impacts, for instance, slow deployment as Firebase has to build large functions, upload and figure out what changed and didn't change.

On top of that, it also makes it very difficult for multiple teams to work on the same project, making it hard to deploy and maintain as teams work on their features.

Firebase Functions Codebases

So, how do you manage this? Firebase provides the concept of Firebase Functions Codebases, where Firebase functions can be organised into a collection in a way that makes sense to an organisation, say a team owns them or by feature, and maintained and deployed together.

The functions collections can be in different repositories or the same repository in a mono-repo setup using something like NX in combination with the NX generator for Firebase that I built earlier this year.

Firebase codebase allows you to organise your Firebase functions collection in a way that makes sense to your organisation. This could be by functionality or teams and so, allowing you to maintain and deploy them together.

By default, firebase has a single default codebase, and your Firebase config file - firebase.json - it looks like this.

{
  // ... other firebase services configurations i.e. hosting etc.
  "functions": [
    {
      "source": "dist/apps/functions",
      // default codebase
      "codebase": "default",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log"
      ],
      "predeploy": [
        "pnpm nx run functions:build"
      ]
    }
  ],
  "extensions": {}
}

We can configure a different codebase for our Firebase functions for a second collection of functions by modifying the codebase property of one of our functions.

For instance, in the above example, we can add a second functions collection with a different codebase by adding a second config option to the functions property inside our firebase.json config file.

{
  // ... other firebase services configs
  "functions": [
    {
      "source": "dist/apps/functions",
      "codebase": "default",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log"
      ],
      "predeploy": [
        "pnpm nx run functions:build"
      ]
    },
     {
      "source": "dist/apps/functions",
      "codebase": "codebase-2",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log"
      ],
      "predeploy": [
        "pnpm nx run functions:build"
      ]
    }
  ]
}

In the case above, our different functions collections exist in the same repository - a mono-repo. We could have our functions collection exist in multiple repositories. In such cases, we would just need the only codebase inside the repository to be configured in our firebase.json config file.

{
  // ... other firebase services configs
  "functions": [
     {
      "source": "dist/apps/functions",
      "codebase": "codebase-2",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log"
      ],
      "predeploy": [
        "pnpm nx run functions:build"
      ]
    }
  ]
}

NB: Ensure that the codebase property is correct, as this could have unforeseen consequences, such as deleting other functions in the codebase that weren't found inside the repository.

Deploying your Functions

As always, firebase deploy and Firebase deploy functions will deploy all Firebase functions within the current directory in all codebases. On top of that, you can specify which codebase to deploy by using the firebase deploy functions:codebase command.

firebase deploy functions:codebase

If your function collections are distributed in multiple repos, you can just use the firebase deploy command. Firebase CLI will not prompt you to delete existing Firebase function collections from other codebases.

But suppose your function collections are in a mono repo setup. In that case, you might find it beneficial to have your target to a specific codebase instead of deploying all codebases within the mono repo.

firebase deploy functions:codebase

Firebase Functions NX Generator

For those of you using NX or want to use NX to manage your Firebase project, you might find it beneficial to try out the generator I created to create Firebase functions as NX apps, with full support for codebase - @nx-toolkits/firebase.

Each Firebase functions codebase lives as an NX application, with all the benefits of NX, such as codesharing between codebases and caching. For more information, check out this post about my motivations as to why I built the generator.

How it works

First, install the @nx-toolkits/firebase generator using your favourite package manager.

// npm
npm i  @nx-toolkits/firebase

// yarn
yarn add @nx-toolkits/firebase

//pnpm
pnpm add  @nx-toolkits/firebase

To generate a function in the default codebase, just run the following command:

nx g @nx-toolkits/firebase:functions

NB: Please ensure that you have run Firebase initialisation in the root directory of your project. In the future, I would like to be able to handle this as well.

This will create or override the default codebase application. To create an NX application with a different codebase, just run the following command:

nx g @nx-toolkits/firebase:functions --codebase codebase-2

And that's it. Running the nx deploy command targeting the app you just generated will only deploy functions of the correct codebase.

nx run my-functions-app:deploy

And that's it.

Conclusion

In this post, we looked at how we can use codebases in Firebase functions to organise our Firebase functions, making it easy to maintain and deploy as our app grows.

It's important for any project to be able to enhance effectiveness and ensure different features can be developed and maintained with minimal conflicts and speed.

Codebases make it easy for organisations to decide how to organise Firebase functions as it makes sense to them, be it in a mono repo setup or even multiple repositories, so as to achieve business goals.

Resources

• Supercharge your Firebase App Development using NX

• The typeof and keyof operators - referencing variable types in Typescript

• Organize multiple functions

• Using Zod Schemas as a Source of Truth for Typescript Types

Now, every angular application, out of the box, by default, uses SSR, which is an opt-out feature. For most people, when building Angular apps, it either needs to be server-side rendered or not; for instance, a dashboard behind a login wall doesn’t need SSR, while an e-commerce site needs it.

However, there are applications where there are some pages that are behind a login wall, and some public routes. If we circle back to our e-commerce site example, checkout pages, order pages, etc., are such examples that are probably behind a login wall, while product pages are public.

If you enable SSR on such a route behind a login wall, and someone visits the page, Angular will render the login page (or wherever the Auth Guards redirect them). When the page is loaded, Angular will determine the user is logged in and redirect them back to the actual page, as shown below:

This means the user will see a flash on the login page before seeing the actual page. This happens because, in our case, the authentication context is only available on the browser, not the server, and hence, on the server, the user is not logged in, but on the browser, the user is.

If you encountered this, like I did, before Angular 19, you would have to disable SSR, as that’s not an optimal user experience. However, the Angular team introduced in Angular 19 the concept of render modes for individual routes, or what is called hybrid rendering.

Instead of all routes either being client-side rendered (CSRd) or server-side rendered (SSRd), you can now choose what to do for each route. On top of that, they also added the ability to perform static site generation (SSG) for individual routes.

Let’s see some code.

Setting Up Server Routes Manually

Before we can go any further, ensure you are on Angular 19. Angular has introduced a concept for Server Routes in which you can declare what to do for certain routes. To take the example above, we have two routes, as shown below:

export const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    canActivate: [redirectIfNotLoggedInGuard],
  },
  {
    path: 'login',
    component: LoginComponent,
    canActivate: [redirectIfLoggedInGuard],
  },
];

We can add server route configurations for the above route configuration using the path and the render mode we need. I chose to store them next to each other, but they can also live in its server routes file - whatever floats your boat.

...
import { RenderMode, ServerRoute } from '@angular/ssr';

...

export const serverRoutes: ServerRoute[] = [
  {
    path: '',
    renderMode: RenderMode.Client,
  },
  {
    path: 'login',
    renderMode: RenderMode.Server,
  },
];

The render mode accepts one of three values, RenderMode.Client, RenderMode.Server, and RenderMode.Prerender. For our very simple example above, we are RenderMode.Client for the home page, so it will not be server-side rendered, and then RenderMode.Server for the login page, it will be server-side rendered.

Once we set up our routes, we finally need to provide the server routes in our app config so that Angular can use them. We achieve this by using the provideServerRouting function and passing in the server routes we configured.

...
import { provideServerRendering } from '@angular/platform-server';
import { provideServerRouting } from '@angular/ssr';
...

export const appConfig: ApplicationConfig = {
  providers: [
    ...
    provideServerRouting(serverRoutes),
    provideRouter(routes),
    ...
  ],
};

And that’s it. If we circle back to our example, we can see that the login page flash is completely gone.

You can find the code for the above application here.

Default Rendering Mode

You can also set the default render mode by using the Angular router catch-all (wildcard) route - **, as shown below:

export const serverRoutes: ServerRoute[] = [
  {
    path: '**',
    renderMode: RenderMode.Client,
  },
  {
    path: 'login',
    renderMode: RenderMode.Server,
  },
];

This will render all pages on the client side except the login page, which will be rendered on the server.

Setting Up For New Projects

Of course, this is Angular we are talking about. With the magic of schematics, you can automate the above process; you will only have to configure your routes.

If you are starting a new project, Angular provides a flag --server-routing that enables this for the new project when setting it up.

ng add @angular/ssr --server-routing

Conclusion

In this brief article, we looked at Rendering Modes in Angular and how we can use them to provide a better user experience for our users. Before this, your options were limited; you could either use SSR or not use SSR if it broke the UX of your users. But with render modes, you can enable SSR where it makes sense, Prerender pages that make sense and CSR pages that make sense, ensuring a much better user experience for our users.

That’s it from me, and until next time, happy coding.

PS: If you are looking to get started with Oh My Zsh, you can find the installation instructions here.

I guess this is the one plugin I can probably not survive with, my flailing memory would suffer greatly to have to remember all my previous commands, even the ones I worked out myself. A close second plugin for my workflow and I believe vital for most developers is the git plugin. It’s just genius.

Subscribe now

Of course, with Oh My Zsh, you have an arsenal of plugins that you can call upon to do your bidding, such as the docker, node, and npm, to mention a few. You can learn more about Oh My Zsh plugins (installation and list of plugins) in the official wiki here.

For a long time, I and the git plugin, have become very close buddies. Want to rebase, push (force push), pull, etc, the plugin will autocomplete everything for you including the git branches, I never get the spelling right on the first try, heck I am even known for copy-pasting them.

I even adapted my naming of git branches, starting with the issue number, followed by the title slug so that I can get even faster autocomplete. Don’t even ask what I was naming them before.

Oh My Zsh Git Aliases

A few months ago, I came across Oh My Zsh git aliases, and well this has transformed my workflow. I can type into my terminal a combination of letters (3 to 5 characters, sometimes 6) and accomplish the same thing I did with a whole sentence.

I know, we as developers have been accused of being overpaid 🤷🏾 and lazy and I am playing up to my character incredibly well here. I will take any shortcut I can to do more, by doing less. On the other hand, I am a huge fan of a good developer experience and I will put anything in my toolbox that improves it, including Github Copilot - I guess I owe another article here as well.

Examples

To show you what I mean, I will demonstrate why I am a huge fan of Git Aliases and why you should start using them. First, with the command that I have always had many struggles with, not because I can’t memorize it, but because I have to remember the branch name - git push -f branch-name.

If you work with Git issues, you probably create branch names for your issues, which could be anything. So, after a rebase against your main branch, you need to push the changes remotely to the PR (for those of us using Github, but there are equivalents for other remove hosting services such as Gitlab), so you need to type the above command:

git push -f whatever-the-****-your-branch-name-is

If you have Oh My Zsh and the Git Plugin, you will probably use it to autocomplete the branch name you want to force push, which is quite helpful. But you can make your life even more easier by using the following git alias:

ggf

Yeah, it’s that simple and will force-push your current branch without you having to worry whether you got the correct branch name or not (god forbid you are not force-pushing on the main branch 🙈). Magic. Now imagine this, you have a few branches that are behind that you want to rebase and force push remotely. This does make your life a little bit easier, doesn’t it?

And did I mention, that it even makes rebasing way easier? So, let’s say, you notice that your branch is behind the origin main branch, instead of checking out the main branch and pulling the changes, you can simply fetch the remote main and merge your branch against it, as shown below:

git fetch origin
git rebase origin/main

If you think typing the above is a lot of work, like me, you can simplify that by using the following Git Aliasis.

gfo && grbom

The above two aliases will fetch the origin branches and rebase the current branch against the origin main branch. And now you can simply run ggf to force push remotely.

Yes, there is a learning curve, of course, you have to memorize the above Aliases, nothing good comes for free. But I believe it’s worth it and they will come naturally to you with time.

Another thing I want to emphasize is that as you go on your way to memorizing and becoming a 10x lazier developer, learn the underlying Git commands, and understand what each Alias you use maps to and what the command does, this way, you will know when not to use an Alias and when to find a different one.

So, if you hear me and want to start using Git Aliases with Oh My Zsh, where do I start? Here are some of the most useful links to installing Oh My Zsh and a cheat sheet for the Aliases to help you memorize them.

• Installing Oh My Zsh

• Oh-My-Zsh Git Cheat Sheet - Kapeli

• Plugins Wiki

Conclusion

In this post, we took a look at how can use Oh My ZSH git aliases to boost our productivity and improve our developer experience, With git aliases we can accomplish more while writing less, this is especially useful when performing rebates and pushing changes across multiple branches where the actions are compressed into just a few characters.

I hope this post convinced you to add Git Aliases to your developer toolbox.

Thank you for reading and until next time, keep on learning.

Control flow is the order in which statements are executed by the computer in a script. We can use conditions (if…else, switch statements) to determine which statements to execute and which to skip when certain conditions are met. We can even repeatedly execute statements using loops.

Subscribe now

Angular is getting a new syntax for control flow, a major departure from what things were (I will refer to it as the old syntax), and still are, as the new control flow syntax is still in the developer preview.

First, let’s compare the new syntax with the old syntax.

If Conditions

Let’s say we want to show a section of our template if the conditions are true. With the old syntax, we would do it like this:

But now, with the all-new syntax, this would look like this:

Or can be further simplified to:

For Loop

What about for loops:

Old

New

As you can see, we are also passing a tracking expression that yields a unique key that we can use to associate the array items and their place in the DOM for performance reasons. This is required in the new control flow syntax, while before with the old syntax, it was optional.

NgSwitch

Here is an example of the old syntax

And here is what that looks like now, with the new syntax

Notice something? The new syntax is more readable (I know, it’s subjective, but I think we can both subjectively agree) and familiar, it looks like the very familiar syntax you would come across while writing Typescript or Javascript (or most languages for that matter). If you are new to Angular, good luck understanding the old syntax without a few head scratches and squinting your eyes.

And then there is another huge benefit, syntax highlighting and formatting. In the old syntax, we didn’t have much in the syntax highlighting corner, as the structural directive we part of the HTML attribute. Since now the control flow isn’t part of the HTML tags, syntax highlighting is already available. On top of that, the prettier npm package (update to the latest version) now supports formatting of the new Angular syntax and it’s just glorious.

Combine these two, and you can now easily tell where one block ends and the other one starts and any nested blocks within the template are easy to identify. This should aid in code readability and improve it exponentially.

And did I mention there is no more unnecessary ng-container and ng-template for conditional HTML blocks? This leads to much cleaner code with less boilerplate.

So far we have seen if and for syntaxes, what about the switch, here is an example.

Improvements over the Old Syntax

→ for loop: required track expression

With the new syntax, providing a track expression that yields a key to keep track of each item in the array to the view location in the DOM for improved performance, especially over large lists is required.

Trying to leave it out, you get the following error:

@for loop must have a "track" expression

On top of that, Angular is using a new optimized algorithm for the for loop so that it’s more performant by making DOM operations as a response to collection changes minimal and hence more efficient.

→ for loop @empty Keyword

On top of that, we now have an @empty keyword that we can use to handle situations where the list is empty, which is kind of neat.

→ readable else

As we saw earlier, doing else in the old control flow syntax in Angular was not really readable and required a lot of boilerplate code, however with the new control flow, it’s much more readable and more familiar, especially for developers just starting out in Angular.

What about the Async Pipe?

Just like before, we can still the async pipe to subscribe to observables just like before.

Within for loops, this is how we can achieve this:

The same can be done for the if blocks:

I am sold, how do I switch?

First, make sure you have updated your Angular project to v17 and then you can run the following schematic to convert existing control flow syntax to the new control flow syntax.

ng g @angular/core:control-flow-migration

When prompted for a path, enter the path to your project and that’s it.

A word of caution, which is a huge step forward in Angular, is that the control flow syntax is in the developer preview. This means some things may change under the hood without following semantic versioning, as it gives the Angular team flexibility to move first and fix issues and concerns that may arise before it’s generally available with the same guarantees Angular provides for all its features.

Next on Unstacked: The all-new @defer syntax

On top of that, Angular is getting a new @defer syntax that can be used to lazy load components, directives, and pipes in the template, until certain conditions are met. I am going to go over this in the next issue of Unstacked in the next couple of weeks as this post is becoming overly long for a newsletter.

Conclusion

In this post, we took a look at the new control flow syntax for angular and the benefits it brings along as compared to the old syntax. We learned that the new control flow syntax is more familiar and subjectively more readable as compared to the old one, and requires less mental gymnastics to understand what’s going on, even for experienced Angular devs, let alone newbies. We also learned how the new syntax not only replaces the old syntax but improves upon it by bringing in extra helpers such as @empty and required track by expression for improved performance.

That’s it from me, and until next time, keep on learning.

Share

On top of that, I also thought this would be a great article for my first-ever post here at Unstacked, a new newsletter that appeals to a broader developer audience, in contrast to my other newsletter - All Things Typescript (whispers - subscribe 😉).

Without wasting any more of your time, let’s dive into today’s issue about web performance and key metrics that you should always keep an eye on.

Agenda

• Why care about your website performance

• Key Metrics to use to measure your Website Performance

Subscribe now

Why?

Websites are a key component of our day-to-day lives. They connect us to vital information, and key services such as Government services, connect with people, and do business among so many things. This means it’s essential that our website provide a decent user experience.

The problem that exists is that while our website may behave as expected on our devices, our users won’t be accessing the device from our devices, but their own and under different circumstances.

This reminds me of this tweet I came across last year, which sadly I didn’t save, which had the following quote:

It’s important as web developers to remember that outside our comfort zone (developers are mostly well paid with access to the latest technologies at their hands), our users are not going to be in ideal locations to access our websites hence the above quote.

For instance in Africa, most people have budget smartphones, with low memory and CPU processing capabilities, and also a gotcha, and these people also live in areas with poor network connectivity such as rural areas.

As developers, we need to ensure that our websites have a decent if not great user experience for users with the cheapest devices and poor network conditions - the lowest common denominator as well for people with more expensive devices and great internet connection.

Metrics

Web Vitals

So, how do you know a website is performing well or poorly? How do you measure the performance of a website? This is where Web Vitals comes in, an initiative by Google to provide unified guidance for quality signals that are essential to delivering a great user experience on the web.

Web Vitals are metrics such as how long it takes for the user to see content on the web page they visited that we can use to understand how well your website is doing. If your website has good performance in these metrics, then the user experience is most likely great, otherwise poor.

Core Web Vitals

We are not going to go into all Web Vitals in this issue, I will leave that up for a future issue. Core Web Vitals are a subset of Web Vitals (goes without saying) and apply to all websites. Each vital in the Core Web Vitals measures important and distinct user experience metrics and reflects the real-world performance of your website, and the list will evolve over time, changing as needed.

As of the time of writing this issue, here are the core web vitals:

Largest Contentful Paint (LCP)

The Largest Contentful Paint (LCP) metric measures the render time of the largest block (text or image) that is visible within the viewport, from the point the page starts to load. This considers images, videos, text blocks, the first frame of animated images, and auto-playing videos, etc.

For your site to have a good LCP score, you need to achieve a score of 2.5s or less, ideally in 75% of all page loads on your websites.

Optimize for the Largest Contentful Paint

When you measure LCP either using Lighthouse or PageSpeed Insight, it usually provides a list of reasons why your LCP was given a certain score and how you can optimize for it.

If you have a website with a poor LCP score, here are some of the things you can do to optimize for LCP.

Improve your server response time

For images, CSS, javascript, HTML, and static files, consider using a CDN, with good caching policies as seen fit. If your server is slow, it impacts another metric called Time To First Byte (TTFB), which measures the time it takes for a request to get the first byte of the response. This is a subset metric for Largest Content Paint (LCP) and First Contentful Paint (FCP).

Optimize for Resource Discovery on your Web Page

Resources impacting LCP should always be loaded as early as possible. Your browser ships with a preload scanner, which will go through your raw HTML before it’s parsed by the browser and look for items it can prefetch such as images, and rel=preload Links.

To optimize for resource discovery:

• ensure that all images have the image URL set inside srset or src attributes for images, don’t use javascript to set image src path for important resources, and

• CSS Background Images and Fonts are preloaded using the <Link rel=preload />.

Give Priority to Important Resources to Loaded Upfront

After optimizing for discovery, it is important to ensure discovered resources are loaded before non-important ones. Resources such as images, that are non-blocking aren’t usually given priority by the browser even when they are discovered by the preload scanner. We can use the fetch-priority attribute to hint to the browser that an image is important and should be given priority.

<img fetchpriority="high" src="/path/to/important/image.webp">

We can also de-prioritize resources, to ensure that we are not taking too much of the browser bandwidth and have enough of it to load important resources.

Others Optimization

• Use modern image formats such as WebP. You can use a specialized image CDN that will automatically serve an image format compatible with the user's device.

• Use Responsive Images. Don’t use one large image for all screen sizes, but instead use responsive images.

• Compress Images to the smallest possible size, without impacting the quality too much.

• Use appropriate cache settings ensuring that network latency is reduced and only necessary for the initial load of the resource

• Remove any unnecessary CSS and Javascript for a page

• Reduce font size

Cumulative Layout Shift (CLS)

One of the most frustrating things to users is when the content they are reading suddenly moves to a different location. This could be caused by things such as an image loading above the content, pushing the content down or some other content being added dynamically such as ads and the content has to move to create space for it.

This is quite difficult to see as a developer as we are usually lucky enough to be using fast or decent-speed internet, images are already cached, which reduces the load time for when we are testing.

CLS is an important metric as it measures unexpected layout shifts during the lifespan of a webpage. A layout shift occurs anytime visible elements to the user suddenly change positions and CLS helps us understand how often our web page is doing this.

There are two types of layout shifts to keep in mind:

• unexpected layout shift - it wasn’t intended by the developer as part of the web page design and is bad,

• and the expected layout shift - think of user-initiated layout shift, like when they click a button to expand a section or animated content.

Ideally, you should have zero layout shifts on your web page, but a good score is 0.1 or less for 75% of all page loads on your website.

To optimize for CLS, ensure that all your images have a fixed height and width, or add aspect ratio to them, so that the browser can reserve a place for them in the rendered page.

First Input Delay (FID)

Ever visited a web page and after it loaded, and you tried to click on a link or button and it took a while for the website to respond? First Input Delay (FID) measures this specific metric of how long it takes for the web page to respond to user interaction such as clicks, taps, and keyboard events during the loading process. For a good FID score, it should have a delay of 100 milliseconds or less.

In order to optimize for FID, you can do the following:

• Reduce or minimize the Javascript that’s initially loaded by your application during the loading process.

• Offload tasks from the main threads, i.e. use Web Workers to perform heavy computations. The main thread is blocking and when the browser is executing Javascript in the main thread, it will not process any user interactions.

• Explore on-demand loading of Scripts as if you load too much on the main thread, it will slow down user interactions.

  • This can be done by deferring unused and unimportant javascript scripts. This can be achieved by adding the defer tag to your scripts. You can learn more about both def and async attributes here.

  • Code-splitting or lazy loading and loading the smaller chunks on demand.

  • And finally, minimize the use of pollyfills.

Interaction to Next Paint (INP)

Ever found yourself on a very sluggish website, where the page was slow to respond and even freezes once in a while? Interaction to Next Paint or INP is a metric that’s designed to measure the general interactivity of your website. Unlike the First Input Delay (FID) metric that focuses on time to first interaction, this focuses on all interactions on your website.

INP measures the latency of keyboard interactions, taps, and clicks during the lifespan of the site. The value of the longest interaction is the INP value, with any outliers ignored. A good INP is below 200 milliseconds.

You can do the following to optimize your INP score:

• Remove unnecessary Javascript from your webpage as it impacts start-up performance. The browser has to download and parse all of the Javascript in order to provide interactivity, and if it’s too much, it means the first interaction will take a bit longer. You can achieve this by using techniques such as Lazy Loading where javascript is broken up into smaller chunks and only necessary Javascript is loaded up.

• Avoid having heavy and long-running tasks on the main thread as they can block other processes hence impacting the performance of your site.

• Minimize the size of the DOM - with large DOM elements, the rendering work takes longer and hence impacts the performance of your Website. With large DOM elements, both the initial rendering and any rerendering afterward are going to be very expensive and slow.

  • You can use content visibility to control whether an element's content is rendered or not.

  • Other techniques include the use of virtual lists where we only render visible parts of lists instead of everything at once, hence improving performance.

• Be aware of the cost of Javascript rendering HTML and CSS. When your browser receives HTML, it can stream it and parse it chunk by chunk, ensuring the best performance. However, with the advent of modern frameworks such as React, Angular, Vue, etc. it’s common to ship a javascript site that then renders the HTML and sometimes even the CSS. This means your browser has to download all the necessary Javascript content, in this case, it will your whole application code (all pages), and then parse it, and only then you will see HTML content. This is very expensive and slow, and we have come up with techniques such as:

  • Server Side Rendering (SSR) where this work is done on the server instead so we can send HTML to the client,

  • and Lazy Loading, where we break up our application into smaller chunks that can be loaded as needed. As developers, however, we need to be aware of this and avoid it where necessary.

Conclusion

In this issue, we talked about Web Performance and important metrics to keep an eye on in order to ensure the user experience is decent if not great. We learned that it’s important to ensure that the lowest common denominator users get a good user experience and can use your website without struggling too much. It’s important for web developers to ensure a website with great performance and great user experience.

Share