DEV Community: Dan Wahlin

AI Repo of the Week: Generative AI for Beginners with JavaScript

Dan Wahlin — Thu, 03 Jul 2025 11:08:07 +0000

A fun, hands-on learning journey that teaches JavaScript developers how to build AI-powered apps using generative AI and large language models.

Introduction

Ready to explore the fascinating world of Generative AI using your JavaScript skills? This week’s featured repository, Generative AI for Beginners with JavaScript, is your launchpad into the future of application development. Whether you’re just starting out or looking to expand your AI toolbox, this open-source GitHub resource offers a rich, hands-on journey. It includes interactive lessons, quizzes, and even time-travel storytelling featuring historical legends like Leonardo da Vinci and Ada Lovelace.

Each chapter combines narrative-driven learning with practical exercises, helping you understand foundational AI concepts and apply them directly in code. It’s immersive, educational, and genuinely fun.

What You’ll Learn

1. 🧠 Foundations of Generative AI and LLMs

Start with the basics: What is generative AI? How do large language models (LLMs) work? This chapter lays the groundwork for how these technologies are transforming JavaScript development.

2. 🚀 Build Your First AI-Powered App

Walk through setting up your environment and creating your first AI app. Learn how to configure prompts and unlock the potential of AI in your own projects.

3. 🎯 Prompt Engineering Essentials

Get hands-on with prompt engineering techniques that shape how AI models respond. Explore strategies for crafting prompts that are clear, targeted, and effective.

4. 📦 Structured Output with JSON

Learn how to guide the model to return structured data formats like JSON—critical for integrating AI into real-world applications.

5. 🔍 Retrieval-Augmented Generation (RAG)

Go beyond static prompts by combining LLMs with external data sources. Discover how RAG lets your app pull in live, contextual information for more intelligent results.

6. 🛠️ Function Calling and Tool Use

Give your LLM new powers! Learn how to connect your own functions and tools to your app, enabling more dynamic and actionable AI interactions.

7. 📚 Model Context Protocol (MCP)

Dive into MCP, a new standard for organizing prompts, tools, and resources. Learn how it simplifies AI app development and fosters consistency across projects.

8. ⚙️ Enhancing MCP Clients with LLMs

Build on what you’ve learned by integrating LLMs directly into your MCP clients. See how to make them smarter, faster, and more helpful.

More chapters coming soon—watch the repo for updates!

Companion App: Interact with History

Experience the power of generative AI in action through the companion web app—where you can chat with historical figures and witness how JavaScript brings AI to life in real time.

Talk with Dinocrates and other historical characters using a custom AI app!

Conclusion

Generative AI for Beginners with JavaScript is more than a course—it’s an adventure into how storytelling, coding, and AI can come together to create something fun and educational. Whether you’re here to upskill, experiment, or build the next big thing, this repository is your all-in-one resource to get started with confidence.

Jump into the future of development—check out the repo and start building with AI today!

AI Repo of the Week: MCP for Beginners

Dan Wahlin — Fri, 23 May 2025 05:51:00 +0000

Introduction

Welcome to this week’s spotlight in our AI Repo of the Week series—introducing the MCP for Beginners course, a fantastic starting point for AI developers and enthusiasts eager to navigate the world of Model Context Protocol (MCP). This open-source GitHub repository offers an in-depth exploration of MCP, an interface designed to extend the capabilities of AI models by integrating them with external tools, APIs, and data sources. Whether you’re new to MCP or looking to strengthen your understanding, this comprehensive resource is a perfect fit.

The repository provides practical lessons and examples that guide developers through creating MCP servers in multiple programming environments, including C#, Python, Java, and TypeScript. A primary goal is to demystify the process of building scalable AI applications by employing standardized protocols. Here’s a quick overview of what you can expect from this repository.

Key Features & Learning Journey

Getting Started with MCP

The “MCP for Beginners” repository kicks off with an introduction to the Model Context Protocol, setting the stage by explaining why a standardized approach matters for scalable AI applications. Users can quickly get their hands dirty with step-by-step lessons designed to implement basic server functionality. This practical approach ensures that you not only learn the MCP theory but also see it in action. The repository is structured to facilitate a smooth learning curve, with each section building on the previous one. Here are a few of the key features you’ll learn about:

Core Concepts Explained : In-depth exploration of the core concepts of MCP, including client-server architecture, key protocol components, and messaging patterns.
First Server Setup : Begin by creating your first MCP server. You’ll explore how to utilize tools like the inspector to test and debug your setups.
Client Development : Progress to building a client that can interact with the MCP server. Special attention is given to enhancing client capabilities using Large Language Models (LLMs).
Advanced Server Integration : Learn to operate MCP servers in various environments, including consumption via GitHub Copilot Agent and Visual Studio Code.

Here’s the complete MCP curriculum structure:

Introduction to MCP Overview of the Model Context Protocol and its significance in AI pipelines, including what is the Model Context Protocol, why standardization matters and practical use cases and benefits.
Core Concepts Explained In-depth exploration of the core concepts of MCP, including client-server architecture, key protocol components, and messaging patterns.
Security in MCP Identifying security threats within MCP-based systems, techniques and best practices for securing implementations.
Getting Started with MCP Environment setup and configuration, creating basic MCP servers and clients, integrating MCP with existing applications.
First server Setting up a basic server using the MCP protocol, understanding the server-client interaction, and testing the server.
First client Setting up a basic client using the MCP protocol, understanding the client-server interaction, and testing the client.
Client with LLM Setting up a client using the MCP protocol with a Large Language Model (LLM).
Consuming a server with Visual Studio Code Setting up Visual Studio Code to consume servers using the MCP protocol.
Creating a server using SSE SSE helps expose a server to the internet. This section will help you create a server using SSE.
Use AI Toolkit AI Toolkit is a great tool that will help you manage your AI and MCP workflow.
Testing your server Testing is an important part of the development process. This section will help you test using several different tools.
Deploy your server How do you go from local development to production? This section will help you develop and deploy your server.
Practical Implementation Using SDKs across different languages, debugging, testing, and validation, crafting reusable prompt templates and workflows.
Advanced Topics in MCP Multi-modal AI workflows and extensibility, secure scaling strategies, MCP in enterprise ecosystems.
Community Contributions How to contribute code and docs, collaborating via GitHub, community-driven enhancements and feedback.
Insights from Early Adoption Real-world implementations and what worked, building and deploying MCP-based solutions, trends and future roadmap.
Best Practices for MCP Performance tuning and optimization, designing fault-tolerant MCP systems, testing and resilience strategies.
MCP Case Studies Deep-dives into MCP solution architectures, deployment blueprints and integration tips, annotated diagrams and project walkthroughs.

Practical Implementation

Throughout the curriculum, you’ll explore key MCP concepts alongside diverse, hands-on samples that demonstrate practical applications in multiple programming languages. For example, a simple calculator server illustrates how MCP principles can be applied to build API endpoints for operations like addition, subtraction, multiplication, and division, complete with type safety and error handling.

Advanced Concepts and Case Study

In addition to covering MCP fundamentals, the course will also walk you through more advanced topics as well. This includes learning about multi-modal integrations, highlighting how AI models can expand beyond text-only capabilities to include data types like images and audio. You’ll also learn about scalable MCP architectures, security, performance optimization, and more.

The course also walks you through an Azure AI Travel Agents case study that demonstrates using MCP in an AI agents scenario.

Conclusion

MCP for Beginners is a great resource for anyone journeying into the realm of AI and MCP development. It provides developers with the necessary knowledge and tools to create flexible and scalable AI applications that can integrate with a variety of data sources.

Dive into the repository, experiment with the provided examples and tools, and quickly get up-to-speed on what MCP is and how you can begin using it. Visit the MCP for Beginners repository on GitHub, star it, and help drive forward the mission of better, standardized AI integrations.

Additional AI Courses

In addition to the MCP for Beginners course, check out the following courses as well:

AI Repo of the Week: GitHub Copilot Adventures

Dan Wahlin — Sat, 03 May 2025 23:49:24 +0000

Welcome to the AI Repo of the Week series! In this first post we’re going to look at the GitHub Copilot Adventures repo. Stay tuned for additional posts that cover AI-related repos across multiple languages and technologies.

GitHub Copilot Adventures

Kickstart your GitHub Copilot journey with GitHub Copilot Adventures, a hands-on playground of “choose-your-own-adventure” coding challenges. In just a few minutes, you’ll go from predicting the next number in a sequence to simulating interstellar alignments, all guided by GitHub Copilot’s AI suggestions. Whether you’re brand new to Copilot or looking to level up your AI-paired programming skills, this repo offers step-by-step scenarios in multiple languages.

Each adventure is packaged as a story—complete with context, objectives, and high-level tasks—so you can dive straight into the code. Behind the scenes, a Solutions directory provides reference implementations in C#, JavaScript, and Python, just in case you get stuck and need a little assistance. By the end of your first run-through, you’ll have explored everything from console apps to HTTP calls, regex-powered text extraction, data structures, and even grid-based battle simulations—all with GitHub Copilot as your AI pair programmer.

Note: GitHub Copilot provides Ask, Edit, and Agent modes. The adventures in this repo rely on what is referred to as “Ask mode” where you prompt the AI for code suggestions.

Choose Your Own Adventure

Several “adventures” are provided in the repo from beginner to advanced. Brand new to GitHub Copilot? Start with the warm-up adventure which will introduce you to some of the core concepts you need to know to get started. From there, you can jump into any of the beginner, intermediate, or advanced adventures and create them using your chosen language. As mentioned, solutions are provided for C#, JavaScript, and Python in case you get stuck and need a little help.

Warm-Up Adventure

Start here if need a quick introduction to GitHub Copilot, what it is, and how you can get started using it.

Chamber of Echoes : Predict the next number in an arithmetic sequence.

Beginner Adventures

The Clockwork Town of Tempora : Calculate clock drift in minutes.
The Magical Forest of Algora : Simulate dance moves to create magical effects.

Intermediate Adventures

The Celestial Alignment of Lumoria : Determine planetary light intensity based on shadows.
The Legendary Duel of Stonevale : Simulate a rock-paper-scissors duel with weighted scoring.
The Scrolls of Eldoria : Fetch and filter secrets using regex from a remote text file.

Advanced Adventures

The Gridlock Arena of Mythos : Build a turn-based grid battle with overlapping moves and score tracking.

Conclusion

By tackling each adventure—from a simple echo chamber to a full gridlock arena—you’ll not only learn core programming concepts across languages but also see firsthand how GitHub Copilot accelerates development, improves code quality, and surfaces best practices to increase your productivity.

Take the next step! Explore the full adventure library, run the code locally (or create your own GitHub Codespace to get started super fast), and unleash the power of AI-paired coding today. Visit the Copilot Adventures repo on GitHub!

Building a Marvel MCP Server with External APIs

Dan Wahlin — Tue, 01 Apr 2025 07:21:03 +0000

Image from the Marvel Developers API

Summary

MCP enables AI models to access external APIs through standardized tool calls, supercharging their capabilities with real-time data and actions.
The Marvel MCP server provides “tools” for interacting with the Marvel API, which is useful for fetching character and comic data and integrating it with AI systems. Even if you’re not coding for the Avengers, it’s a great way to learn MCP integration and create an MCP server for your own APIs.

Introduction to Model Context Protocol (MCP)

Ever wish your AI assistant could tap into external APIs, fetch live data, or interact with tools beyond its built-in knowledge? That’s exactly what the Model Context Protocol (MCP) enables. MCP is a standardized way for AI systems to discover available tools, send them inputs, and get back results in a consistent format. It’s a powerful way to extend what AI can do—especially for things like making API calls or querying databases, which models can’t do on their own. Think of it as the Rosetta Stone between AI models and the outside world.

To make this real (and fun), I put together a Marvel-themed MCP server. It acts as a bridge to the Marvel API, letting you pull in data about characters, comics, and more—perfect for giving AI apps some superhero flair.

Now, I realize that unless you’re working at Stark Industries, you probably won’t be using Marvel data in your day job. But hey, capes or not, this project gives you a practical blueprint for building your own API-connected MCP server that works with tools like Claude Desktop or GitHub Copilot in VS Code.

Project Overview

I originally built the Marvel MCP server project to experiment with integrating API data into AI systems. I needed some realistic APIs to use and the Marvel APIs worked really well. They’re rich, fun to explore, and perfect for a demo that’s a little more exciting than pulling weather data.

The project’s structure includes several key files:

src/index.ts : Sets up the MCP stdio server and handles requests for listing and calling tools.
src/tools/tools.ts : Defines MCP tools used to interact with the Marvel API, each with a description, input schema, and handler function. Each tool is in its own folder and defines the schemas it needs and the overall functionality.
src/tools/schemas.ts : Contains shared Zod schemas used by tools that call the Marvel API. The schemas are generated from the Open API spec available from https://gateway.marvel.com/docs/public.
src/utils.ts : Provides utility functions used by the MCP server tools to handle authentication (via public and private keys that the Marvel Developer API provides) and HTTP requests.
src/instructions.ts: Provides general prompts used across all tools.
src/server.ts and src/streamable-http.ts: The MCP server can be run as stdio (that’s the default option to use it in an MCP host – more on this later). However, these two files enable running the new streamable HTTP option available.

Let’s walk through several of these files and highlight key aspects that are used to create the MCP server.

The Role of Schemas

APIs can have input parameters and return a specific type of response. MCP tools need to know what to pass to an API endpoint and the type of response to exact. That’s where schemas come into play. Each tool folder such as tools/get_characters has the schemas used by the tool and well as the functionality to call the target API endpoint. Schemas define input parameters passed from the tool to the API (filters, IDs, etc.) as well as the shape of the response (ID, name, description, etc.). Schemas rely on the Zod npm package to define an object’s structure and data types.

Here’s an example of how Zod is used to create GetCharactersSchema which is located in the tools/get_characters/schemas.ts file.

CharactersSchema

export const GetCharactersSchema = z.object({
  name: z.string().optional(),
  nameStartsWith: z.string().optional(),
  modifiedSince: z.string().optional(),
  comics: z.string().optional(),
  series: z.string().optional(),
  events: z.string().optional(),
  stories: z.string().optional(),
  orderBy: z.string().optional(),
  limit: z.number().min(1).max(100).optional(),
  offset: z.number().optional(),
});

This schema defines the input parameters used to fetch characters from the API:

Optional filters like name, nameStartsWith, and modifiedSince for searching and date filtering.
Optional comma-separated lists for comics, series, events, and stories to filter by related entities.
orderBy for sorting results, and limit and offset for pagination, with limit constrained between 1 and 100.

In addition to input schemas, there are also output schemas as mentioned earlier. Here’s an example of CharacterSchema which represents the shape of the data in the API response. Because it’s used across multiple tools, it’s defined in tools/schemas.ts.

CharacterSchema

export const CharacterSchema = z.object({
  id: z.number(),
  name: z.string(),
  description: z.string(),
  modified: z.string(),
  resourceURI: z.string(),
  urls: z.array(UrlSchema),
  thumbnail: ImageSchema,
  comics: ListSchema(ComicSummarySchema),
  stories: ListSchema(StorySummarySchema),
  events: ListSchema(EventSummarySchema),
  series: ListSchema(SeriesSummarySchema),
});

This schema defines a Marvel character, including:

id : A numeric identifier.
name : The character’s name as a string.
description : A character description.
modified : A string representing the last modification date.
resourceURI : The canonical URL for the character.
urls : An array of UrlSchema objects, likely for external links.
thumbnail : An ImageSchema for the character’s image.
comics, stories, events, series : Lists with respective summary schemas.

This schema ensures that any character data received from an API call conforms to the schema structure, which helps an AI system better understand the data it receives.

Creating schemas by hand is really tedious, so I used Grok 3 to convert portions of Marvel’s OpenAPI spec into the desired schemas. GitHub Copilot, ChatGPT, and others should be able to handle the conversion for you as well.

The Role of Tools

One of the key features of MCP servers is tools. Tools allow an LLM used within an AI system to perform actions through the MCP server. Think of tools as buttons the AI can press to go do something useful—like asking the Marvel API for data.

The src/tools/tools.ts file defines several tools for the Marvel MCP server, each with a description, schema, and handler. Here’s an example of the get_characters tool used to call the Marvel API.

get_characters Tool

export const get_characters = {
    description: `Fetch Marvel characters with optional filters.`,
    schema: GetCharactersSchema,
    handler: async (args: any) => {
        const argsParsed = GetCharactersSchema.parse(args);
        const res = await httpRequest('/characters', serializeQueryParams(argsParsed));
        return CharacterDataWrapperSchema.parse(res);
    }
};

Description : Fetches Marvel characters, allowing optional filters like name, modification date, and related entities.
Schema : Uses GetCharactersSchema, ensuring inputs are validated against expected parameters.
Handler : Parses the input using GetCharactersSchema, serializes query parameters using serializeQueryParams from utils.ts, makes an HTTP request to Marvel’s /characters API using httpRequest (also in utils.ts), and parses the response with CharacterDataWrapperSchema. This ensures the response conforms to the expected character data structure and helps the AI system understand the data it receives.

Another tool is get_comics_for_character:

export const get_comics_for_character = {
    description: `Fetch Marvel comics filtered by character ID and optional filters.`,
    schema: GetComicsForCharacterSchema,
    handler: async (args: any) => {
        const { characterId, ...rest } = GetComicsForCharacterSchema.parse(args);
        const res = await httpRequest(`/characters/${characterId}/comics`, serializeQueryParams(rest));
        return ComicDataWrapperSchema.parse(res);
    }
};

Description : Fetches comics featuring a specific character, with additional optional filters like format, date range, and more.
Schema : Uses GetComicsForCharacterSchema, ensuring input validation.
Handler : Parses the input, extracts characterId and other parameters, makes a request to /characters/{characterId}/comics with serialized query parameters, and parses the response with ComicDataWrapperSchema, ensuring comic data integrity.

The src/tools/tools.ts file aggregates all of the available tools:

import { get_characters } from './get_characters/index.js';
import { get_character_by_id } from './get_character_by_id/index.js';
import { get_comics_for_character } from './get_comics_for_character/index.js';
import { get_comics } from './get_comics/index.js';
import { get_comic_by_id } from './get_comic_by_id/index.js';
import { get_characters_for_comic } from './get_characters_for_comic/index.js';

export const marvelTools = {
    get_characters,
    get_character_by_id,
    get_comics_for_character,
    get_comics,
    get_comic_by_id,
    get_characters_for_comic
};

export type ToolName = keyof typeof marvelTools;

These tools demonstrate how the server abstracts Marvel API calls, providing a standardized interface for MCP interactions. The input schemas help the AI system understand what data it needs to pass and the output schemas help the AI system’s LLM understand the data it recevied.

Utility Functions

Looking at the previous tools, you may have noticed that an httpRequest() function handles the calls to the Marvel API endpoints. It’s located in src/utils.ts. Here’s what the function looks like.

httpRequest()

export async function httpRequest(endpoint: string, params: Record<string, string | number | undefined> = {}) {
  const url = new URL(`${MARVEL_API_BASE}${endpoint}`);

  const authParams = createAuthParams();
  url.searchParams.set('ts', authParams.ts);
  url.searchParams.set('apikey', authParams.apikey);
  url.searchParams.set('hash', authParams.hash);

  for (const [key, value] of Object.entries(params)) {
    if (value !== undefined) {
      url.searchParams.set(key, String(value));
    }
  }

  const res = await fetch(url.toString());
  if (!res.ok) {
    const text = await res.text();
    throw new Error(`Marvel API error: ${res.status} - ${text}`);
  }

  return res.json();
}

Purpose : Makes HTTP requests to the Marvel API, handling authentication with timestamp, API key, and hash, and ensuring error handling for non-OK responses.
Usage : Called by tool handlers to fetch data, ensuring secure and reliable API interactions.

The MCP Server

MCP servers can support a variety of transport types including stdio, SSE, and HTTP streaming (the newest option). Think of your MCP server quietly listening like Jarvis in the background, ready to take orders via stdin and reply via stdout as an AI system needs more information. The Marvel MCP server uses stdio by default since it’s currently supported by most MCP hosts such as Claude Desktop and GitHub Copilot in VS Code. However, the project also supports the streamable HTTP transportas mentioned earlier.

An MCP server running with stdio acts like a background process that listens for JSON-formatted tool calls via standard input, processes the requests (like calling an API or performing a task), and then returns the results via standard output.

Here’s some of the key code in the Marvel MCP server’s src/index.ts file including how the server is initialized, how tools are exposed to MCP clients, and how individual tools are invoked.

Initializing the MCP Server

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { zodToJsonSchema } from 'zod-to-json-schema';
import { marvelTools, ToolName } from './tools.js';

...

const server = new Server(
  {
    name: 'marvel-mcp',
    version: '1.5.0',
    description: 'An MCP Server to retrieve Marvel character information.',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

Initializes the MCP server with metadata, including name, version, and description, and specifies that the server supports tools.

List Tools Request Handler

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: Object.entries(marvelTools).map(([name, tool]) => ({
      name,
      description: tool.description,
      inputSchema: zodToJsonSchema(tool.schema),
    })),
  };
});

Handles requests to list tools, mapping each tool from marvelTools (shown earlier) to include name, description, and input schema.

Call Tool Request Handler

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  console.error(`Processing tool request: ${request.params.name}`);

  if (!request.params.arguments) {
    throw new Error('Arguments are required');
  }

  const { name, arguments: args } = request.params;

  if (!(name in marvelTools)) {
    throw new Error(`Unknown tool: ${name}`);
  }

  const tool = marvelTools[name as ToolName];

  if (!tool) {
    throw new Error(`Tool not found: ${name}`);
  }

  try {
    const result = await tool.handler(args);
    console.error(`Completed tool request: ${name}`);

    return {
      content: [{ type: 'text', text: JSON.stringify(result) }],
    };
  } catch (error) {
    if (error instanceof Error) {
      throw new Error(`Error processing ${name}: ${error.message}`);
    }
    throw error;
  }
});

Handles requests by an AI system to call a specific tool, validating the input, checking if the tool exists, executing the handler, and returning the result as JSON.

This setup ensures the server can respond to MCP protocol requests, providing a robust interface for tool interactions.

Using the MCP Server in an MCP Host

Now that you’ve got your MCP server built, how do you connect it to something like Claude or Copilot? It’s easier than you might think. Just a bit of configuration and you’re off to the races.

For example, to use the Marvel MCP server with Claude Desktop you can add the following JSON into the claude_desktop_config.json file.

Claude Desktop MCP Server Configuration

{
  "mcpServers": {
    "marvel-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@codewithdan/marvel-mcp"
      ],
      "env": {
        "MARVEL_PUBLIC_KEY": "YOUR_PUBLIC_KEY",
        "MARVEL_PRIVATE_KEY": "YOUR_PRIVATE_KEY",
        "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public"
      }
    }
  }
}

To use the server with GitHub Copilot in VS Code you can add the following section to your settings:

VS Code MCP Server Configuration

"mcp": {
 "servers": {
     "marvel-mcp": {
         "command": "npx",
         "args": [
             "-y",
             "@codewithdan/marvel-mcp"
         ],
         "env": {
             "MARVEL_PUBLIC_KEY": "YOUR_PUBLIC_KEY",
             "MARVEL_PRIVATE_KEY": "YOUR_PRIVATE_KEY",
             "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public"
         }
     },
 }
}

You’ll notice that two keys are needed. You can get those from the https://developer.marvel.com website after registering.

What if you don’t want to store keys directly in the file? With VS Code you can use the following confirmation. When you start the MCP server you’ll be prompted to enter the key and it’ll store it for you (but not show it). Here’s what that configuration looks like:

VS Code MCP Server Configuration with Inputs

"mcp": {
  "inputs": [
      {
          "type": "promptString",
          "id": "marvel-public-api-key",
          "description": "Marvel public API Key",
          "password": true
      },
      {
          "type": "promptString",
          "id": "marvel-private-api-key",
          "description": "Marvel private API Key",
          "password": true
      }
  ],
  "servers": {
    "marvel-mcp": {
        "command": "npx",
        // "command": "node",
        "args": [
            "-y",
            "@codewithdan/marvel-mcp"
            // "/PATH/TO/marvel-mcp/dist/index.js"
        ],
        "env": {
            "MARVEL_PUBLIC_KEY": "${input:marvel-public-api-key}",
            "MARVEL_PRIVATE_KEY": "${input:marvel-private-api-key}",
            "MARVEL_API_BASE": "https://gateway.marvel.com/v1/public"
        }
    }
  }
}

Once the configuration is in place and the MCP server is started by selecting the Start option above “marvel-mcp” in the file, the @codewithdan/marvel-mcp package will be downloaded from npm and the server will be run locally. From there, a user can interact with the MCP host and ask questions about Marvel characters and comics. Here’s an example of doing that from GitHub Copilot.

Examples of additional prompts could include:

What comics is Wolverine in?

Which characters appear in the Avengers comics?

What characters are in the Hedge Knight II: Sworn Sword (2007) comic?

Once the MCP server’s tools are known to the MCP host, the AI system should call them anytime it needs an answer that it can’t provide on its own.

Conclusion

And there you have it—your very own MCP server powered by the Marvel universe! While you might not be saving the world with superhero data in your day job, this project gives you a solid blueprint for integrating any external API into an AI system using the Model Context Protocol.

Peek under the hood at the code, schemas, tools, and server setup, and you’ll be well on your way to building your own API-powered AI sidekicks. Whether it’s fetching weather data, querying a knowledge base, or interfacing with your company’s internal tools, the process is the same.

Key Resources

Getting Started with Azure Static Web Apps

Dan Wahlin — Mon, 14 Nov 2022 21:13:00 +0000

What does it take to deploy a modern JavaScript web app? Your initial response might be, “Copy the files up to the server – how hard could it be?”.

The reality is that deploying modern JavaScript apps is a bit more complicated than simply copying files up to a server. For example, let’s say that you have a Single Page Application (a static web application) built with React, Vue, Angular, or another technology that hits an API, supports user logins and roles, and has to secure specific server-side routes. To deploy the app you’d need to do something like the following at a minimum:

Build the application and generate the bundles.
Build the APIs (depending upon what technology is used).
Setup a server that can host the SPA bundles and run the APIs.
If the static web app and APIs are on separate servers, configure CORS or a reverse proxy.
Configure SSL on the server.
Add a custom domain.
Configure a default fallback route so that the static web app’s client-side routes work properly and you don’t get a 404.
Deploy the SPA bundles to the server.
Deploy the API binaries or scripts up to the server.

Are there any additional considerations to take into account? Definitely! Here are a few additional ones:

Create a “staging” environment that mirrors the production environment so that you can do testing and QA before going to production.
Integrate user authentication and authorization from a cloud provider or 3rd party and secure application routes.
Automate the build process for the static web app and APIs and create a build pipeline.
Deploy the static web app to a CDN or to multiple servers around the world.
Deploy the app’s APIs to a cluster of servers if they need to handle variable loads.
More…

Whew….that is a lot of work! Isn’t it supposed to be easy to deploy a static web app and get it up and running? When you factor in the creation of a “staging” site, authentication/authorization, server configuration, dealing with server-side and client-side routes, global distribution of your app (if required), and other requirements your head can start to spin.

Are there any services out there that can help simplify the process of deploying a static web app and its associated APIs? You always do it yourself using various cloud provider services but you’d have to setup storage, web hosting, APIs, manage build and deployments, SSL certs, custom domains, handle security, and much more. You could also use services like Netlify (https://netlify.com), Firebase (https://firebase.google.com), and many others as well.

Fortunately, there’s a new kid/service on the block. Azure Static Web Apps. I already use Azure for all of my deployments so I’m really excited about this relatively new functionality Microsoft has added to Azure. Let’s look at how it works.

If you’d prefer to watch a video, here’s one I created that also goes through the steps discussed in this post.

Getting Started with Azure Static Web Apps

Introducing Azure Static Web Apps

Microsoft announced the Azure Static Web Apps service at the Build 2020 conference so it's been out for awhile now. I was fortunate to get early access back then and have been really impressed with the functionality they’re providing. Since then, they’ve made the service “GA” (generally available) and currently support 2 plans. The free plan allows you to get started absolutely free while the standard plan includes all of the free features as well as the ability to customize functionality such as authentication and APIs.

You can view pricing details for the standard plan at https://azure.microsoft.com/en-us/pricing/details/app-service/static.

Here are the basic steps to get started with Azure Static Web Apps:

Push your app code to Github.
Sign-in to the Azure Portal, search for “Static Web App”, and select the Create button.
Fill out the form, sign-in to Github, and select your repository and branch.
Define where your app, APIs, and build output are located.
Select the Create button and watch the magic happen!
View your static web app.

Before going through these steps you’ll need to have an Azure account. If you don’t have one you can setup a free trial account at https://azure.microsoft.com/free. Let’s walk through each of these steps.

Step 1. Push Your App Code to Github

If you’re already using Github to store your code then this first step is the easiest of all. If you’re new to Github check out how to started using it. Believe it or not, once your static web app is on Github and your app is ready to try out, the hard part is done!

If your app has APIs that you want to host in Azure then you can use Azure Functions (Node.js 12, .NET Core 3.1, or Python 3.8 are supported – check the docs for updates). You can use Azure Static Web Apps without any APIs at all of course. Maybe you have a truly static web app that doesn’t need to call out to a server for data. Or, if your app does have APIs and they’re hosted somewhere else that’s fine too. They’re flexible!

If your app does have APIs that you want to host in Azure and you’re new to Azure Functions, here’s a quick overview of what they are and what you can do with them. Azure Functions provide a “serverless” environment for hosting a variety of APIs that can serve data over HTTP or integrate with other Azure services. An Azure Function written with JavaScript consists of an index.js file that contains your code as well as a function.json file that defines the inputs and outputs for the function. Here’s an example of a function that is triggered by an HTTP request and returns JSON: function that is triggered by an HTTP request and returns JSON:

const customers = require('../data/customers.json');

module.exports = async function (context, req) {
    context.res = {
        headers: {
          'Content-Type': 'application/json'    
        },
        body: customers
    };
}

The input and output bindings (the type of data that flows in and out of the function) can be defined in the function.json file. Here’s an example of input/output bindings for the previous function:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get"
      ],
      "route": "customers/"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

This function is triggered by an HTTP GET request to https://[yourserver.com]/api/customers. The incoming request object is named req. The function returns a response using an object named res. Although a complete discussion of Azure Functions is outside the scope of this post, they’re really powerful and definitely worth looking into more.

Once your static web app and Azure Functions APIs are up on Github, you’re ready to create a static web app service in Azure. Let’s look at that process.

Step 2. Sign-in to the Azure Portal, Search for “Static Web Apps”, and click the Create button

Searching for the Static Web Apps resource in the Azure portal.

Visit https://portal.azure.com, sign-in, and use the search box at the top to locate the Static Web Apps service. Select it to get to the service’s information page. Take a few moments to read about what the service offers and when you’re ready, click the Create button to get started.

Step 3. Fill Out the Form, Sign-in to Github, and Select Your Repository

In this step you’ll fill out the Static Web Apps form and sign-in to Github to select your repository. Here are the fields to fill out:

Select your Azure subscription.
Create or select a Resource Group (a container that holds related resources such as your new static web app functionality)
Name your app.
Select a region.
Select a SKU/plan.
Sign-in to Github and select your org, repo, and branch.

Once you’re done filling out the form click the Next: Build > button.

Step 4: Define Where Your App, APIs, and Build Output are Located

Create a Static Web App

The next step is to define where your app is located in the repository, where your Azure Functions APIs are located, and the directory where your build artifacts (your bundles) are located. You can even preview the workflow file that will be added to your Github repository.

After entering that information click the Review + create button.

WARNING: Make sure you enter correct values for your root app location (where your package.json file lives), API location (where your Azure function APIs live if you’re publishing them to Azure), and whatever directory your app builds to (note that this is relative to where your app location is) because this will NOT work otherwise. I’ll provide more information about checking out your build status later in this post.

5. Click the Create Button and Watch the Magic Happen!

It’s time to launch your static web app! Review the summary information provided and then click the Create button. Go grab a coffee, kick back, relax, and watch a (super short) YouTube video while a Github Action builds your code and deploys it to Azure automatically.

Step 6: View Your Static Web App

OK – coffee time’s over! Once your static web app is created, click the Go to resource button.

Go to your newly created static web app and click the site’s URL to view it.

If you’d like to see the build in action on Github, click the blue arrow above the site’s URL (note that this will disappear after a while) or the GitHub Action runs link:

Here’s an example of what the Github Action build created in your repository by Azure Static Web App looks like. This repository is located at https://github.com/DanWahlin/Angular-JumpStart if you want to try one out that already has an app and functions available. Every time you push code to your chosen repository branch the Github Action build process kicks off automatically.

Let’s look at an app that was deployed to Azure Static Web Apps.

Deploying a Static Web App and API

To try out the new Azure Static Web Apps functionality I decided to use a sample Angular project I have on Github called Angular Jumpstart. It originally relied on Node.js/Express for the back-end APIs and is easy to get going locally. See the README.md file for more details on getting it running on your machine.

The challenge with the original version of the app was that I needed to understand what Azure Static Web Apps wanted and I needed to convert my existing Node.js RESTful APIs into Azure Functions (I no longer need a server to host the APIs on which is great!). You can find documentation on the conversion process on the Microsoft docs site if you’re interested.

After getting everything in place I decided there was no time like the present to get things started. I went through the steps listed above to create the Azure Static Web App and my first build started on Github. Looking good….looking good….damn…it failed. I hadn’t read any of the docs at this point but I figured it’d be interesting to see how things went without any modifications (aside from the Node –> Azure Functions conversion).

It turned out that the first build failed due to putting an incorrect path in for the build output (step 4 above). I fixed that, got the build working, and successfully deployed the site. Success….or so I thought. While the shell of the site loaded, none of the API calls worked which meant no data loaded into the web page.

I jumped on a call with my buddy John Papa from Microsoft (fortunately for me he had been spending a lot of time with this new service) and he had me adjust a few things in my functions. The main change was “api” needed to be taken out of the route values in the function.json files. For example, api/customers was converted to customers.

Once that change was made along with a few other minor ones, the site sprung to life. However, if I refreshed the page I got a 404 error because the route was evaluated on the server-side instead of redirecting back to index.html. Azure Static Web Apps to the rescue! They have a nice routing solution (which I’m only going to scratch the surface on in this post) that lets you handle the proper redirect to the static web app client-side routes.

You can add a staticwebapp.config.json file into the root of your project to handle redirecting:

{   
  "navigationFallback": {     
    "rewrite": "/index.html" 
  } 
}

Once I added the staticwebapp.config.json file the site was rebuilt/redeployed and everything worked as expected. You can get more information about routing, handling client-side redirects, and even securing server-side APIs using authentication/authorization in the Azure Static Web Apps docs.

Now any time I want to make a change I simply push it up to Github, that kicks off the Github Action build process and deployment, and the change is in production on Azure within a few minutes. Pretty amazing! Feel free to clone the Angular Jumpstart project and try out the steps shown earlier on your own.

Conclusion

Although deploying modern JavaScript apps can be pretty challenging when you factor in all of the required tasks, Azure Static Web Apps greatly simplifies the process and makes it a piece of cake to deploy an app once you have it setup and configured.

NOTE: If you’re building Microsoft Teams apps then Azure Static Web Apps can provide a great way to host your Teams app depending on the technology used by the app!

So what’s next? There’s quite a bit more you can do with Azure Static Web Apps such as:

Add a custom domain to your static web app using the Azure portal.
Create a staging slot in Azure Static Web Apps to test your app (for example test a pull request) before swapping it over to production.
Add authentication/authorization using Microsoft, Google, Facebook, Twitter, or Github. You can add users, associate roles with back-end routes and more.
Although this example shows an Angular application, you can deploy many other app types as well:
- React
- Vue
- Hugo
- Svelte
- Gatsby
- Next.js
- More…

Take Azure Static Web Apps for a spin and see what you think! Here are some additional links you can visit to learn more.

Static Web Apps docs: https://aka.ms/azure-swa-docs
Static Web Apps Learn modules (Angular, React, Svelte, or Vue JavaScript app and API): https://aka.ms/azure-swa-learn
Static web app with the Gatsby static site generator: https://aka.ms/azure-swa-gatsby

Video: Show a user’s emails in an ASP.NET Core app using Microsoft Graph

Dan Wahlin — Mon, 14 Nov 2022 21:08:46 +0000

I’ve been working a lot with .NET Core and Microsoft Graph lately and decided to put together a short video based on a Microsoft Learn module covering how the technologies can be used together. If you haven’t used Microsoft Graph before, it provides a secure, unified API to access organizational data and intelligence (data stored in Microsoft 365 for example).

So why would you ever want to access a signed in user’s emails and include them in your custom app? The simple answer is, “Bring organizational data where your users need it everyday!”. Instead of users switching from your app to find a relevant email, calendar event, Microsoft Teams chat (and more) by jumping between various productivity apps, you can pull that type of data directly into your custom app. This allows users to work more efficiently and make more informed decisions all while minimizing context shifts.

In this video I’ll introduce you to:

The role of security in making Microsoft Graph calls.
Microsoft Identity and Microsoft Graph Middleware configuration.
The role of permissions/scopes and access tokens.
The Microsoft Graph .NET Core SDK and how it can be used.
How to create reusable classes that handle making Microsoft Graph calls.
Dependency injection and how it can be used to access a GraphServiceClient object.
How to retrieve a batch of email messages using the UserMessagesCollectionRequest class.

Show a user’s emails in an ASP.NET Core app using Microsoft Graph

New Video Series: All Things Microsoft Cloud

Dan Wahlin — Mon, 14 Nov 2022 21:06:33 +0000

I had a chance to sit down with my colleagueAyça Baş as well as several special guests to talk about how different technologies across the Microsoft Cloud can be integrated together to build a variety of applications. Check out the different interviews in the video series below.

What is the Microsoft Cloud?

Ayça and I talk about the overall Microsoft Cloud and services that are available. While Azure is a central part of the Microsoft Cloud, you can also integrate with services across Microsoft 365, Power Platform, and GitHub. Ayça and I also discuss a new Build applications on the Microsoft Cloud document that walks IT leaders, architects, and developers through the options available to leverage everything the Microsoft Cloud has to offer.

Microsoft Cloud and Microsoft Graph

In this video we talk with Yina Arenas about the role of Microsoft 365 and Microsoft Graph in the overall Microsoft Cloud. Yina shares the story of how Microsoft Graph was created and discusses the powerful APIs it offers to enable developers to integrate Microsoft 365 (and other) data into their applications.

Microsoft Cloud and Power Platform

In this video we talk about the role of Power Platform in the overall Microsoft Cloud. April Dunnam discusses how to get started with Power Platform, what fusion development is, how to integrate with different APIs using connectors and Azure API Management, the VS Code extension for Power Platform, and more.

Microsoft Cloud and Microsoft 365/Microsoft Teams

In this video we talk about the role of Microsoft 365 and Microsoft Teams in the overall Microsoft Cloud. Bob German discusses how to get started building apps for Microsoft Teams using Power Platform and how custom apps and services can be built using the Teams Toolkit. He also shares information about a Microsoft Teams App Camp workshop that developers can take to dive in deeper.

Microsoft Cloud and Accessibility

Accessibility plays a prominent role across Microsoft Cloud services. In this video we talk with Dona Sarkar about different accessibility features built-into cloud services and tools that developers can utilize to increase accessibility in their custom applications.

Microsoft Cloud and GitHub

In this video we talk with Todd Anglin about how GitHub fits into the overall Microsoft Cloud and some of the technologies you can use to simplify integration with Azure.

Getting Started Calling the Microsoft Graph API

Dan Wahlin — Fri, 04 Nov 2022 04:48:01 +0000

In this post I’m going to share a quick tip on how to get started calling the Microsoft Graph API. If you’re new to Microsoft Graph, here’s a short definition for you:

Microsoft Graph provides a secure and unified API that can be used to access Microsoft 365 and other cloud data and intelligence.

NOTE: You can watch a video about everything covered here on the Microsoft 365 Developer YouTube channel.

In a nutshell, you can use Microsoft Graph to retrieve information about users, groups, emails, Teams chats, OneDrive files, meetings, to-do list tasks, and much more and then pull that data into apps where your users work every day.

Retrieving Microsoft 365 Data

That means if I’m the user using your application, I can login and I see my list of meetings or files related to a particular topic listed right in the app. Or, if I have emails that are related to a particular scenario, I can see my emails after logging in. Of course, this is all done in a secure manner where the user has to consent and give their approval.

Before moving on, it’s important to clarify one thing: Microsoft Graph isn’t graph DB or GraphQL. Microsoft Graph is a RESTful API so the same principles you’ve likely used with other APIs (Web API with .NET, APIs exposed using Express/Node.js, and so forth) can be used.

To get started with Microsoft Graph you can use the Microsoft Graph Explorer. At the Microsoft Graph Explorer website you can see what Microsoft graph APIs are available and practice using them all within the confines of the browser. For example, in the images below you’ll notice there is an area where you can select a sample query to run and an area where the API’s URL is defined. Select the “my profile” option in the Sample queries section to get started.

Microsoft Graph explorer sample queries

Microsoft Graph explore API URLs

As mentioned, Microsoft Graph is a RESTful API used to get Microsoft 365 data. For example, I can call into the profile API and get the logged in user’s profile using the following URL (shown above in the previous image):

https://graph.microsoft.com/v1.0/me

When you first go to the Microsoft Graph Explorer you won’t be logged in. That means you’ll be getting anonymous data back for a user’s profile and you’ll see a display name of Megan Bowen is used. You can also get some information about Megan’s email address and some other info as well in her profile. Notice that the data returned is JSON (JavaScript Object Notation) data.

JSON data returned for a user’s profile.

In addition to that, you can run other queries. If you want to do this for Megan (the anonymous user you’ll see) you can leave it as is, but if you want to do it for yourself, you can either log in with your credentials or better yet you could log in with a free developer tenant so that you can safely play around.

If you go to the sample queries section and click on “my photo” you’ll see Megan’s photo displayed in the browser. Look at the API URL and you’ll notice the following value displayed:

https://graph.microsoft.com/v1.0/me/photo/$value

If you delete $value , you’ll get back JSON data about the image. Notice that it contains height, width, and some other data as well.

Data returned about a user’s profile image.

You can get to Megan’s email messages as well. I want to emphasize again that you have to have a logged in user who has consented to access this information. If you want to display a user’s email messages, they’d have to log in first. If they approve it, you could pull their mail in and display it to them in an app.

For example, maybe you’re working on a sales application right now, and you want to pull in sales specific emails so that they can see what they’ve said in the past to customers. You could filter based on subject, for example, and then display the body of the message to the sales person after they’ve logged in.

You can also retrieve calendar events and more. If you go the sample queries search box (lower left of the screen) and type “calendar” you’ll notice you can retrieve calendar events for the next week or all events. Maybe you want all upcoming events but only want to retrieve a limited amount of data about each event. If you click on the “all events in my calendar” query you can get that data. Looking at the JSON that’s returned you’ll see quite a bit of data displayed.

If you only want the subject , body , and maybe the start and the end dates, you can adjust that in the URL by deleting the properties you don’t want. The properties to return in the JSON data are controlled using the $select query parameter.

Changing returned properties using the $select query parameter.

Now run the query and you’ll notice that only those properties are returned. You can also add different types of filtering if you’d like. You can add an & to the end of the URL and type $filter equals “your query here”. Or, you can grab something greater than a date, less than a date, etc. Here’s an example of using ge to grab calendar events greater than or equal to a specific date. Notice the use of the $filter query parameter.

Using the $filter query paramter

After selecting Run query you’ll have the same data, but now it’s filtered and only the specific properties you selected are returned! Additional information about selecting, querying, sorting, and performing other types of operations can be found at https://aka.ms/msgraph-query-params.

Conclusion

I hope this helps you out as you get started using Microsoft Graph. If you’d like a more hands-on approach to using Graph Explorer and Microsoft Graph in general, check out the free
Microsoft Graph Fundamentals learning path available at https://aka.ms/learn-graph or watch the video course at https://aka.ms/ms-graph-video-course.

Start Learning TypeScript with These Short Videos

Dan Wahlin — Fri, 04 Nov 2022 04:41:59 +0000

TypeScript continues to grow in popularity and for good reason. It adds “guard rails” to your code to help you spot issues early on, easily locate problem code, enhance productivity, provide consistency across code, and much more. While there are a lot of TypeScript resources out there to get started learning the language, where can you go to get started quickly without wasting a lot of time?

I recently published a series of short videos on TypeScript core concepts that can provide a great starting point. The videos are short, super focused, and many of them use the online TypeScript Playground to demonstrate different concepts. There are a few videos on getting started working with TypeScript locally on your machine as well.

Here’s more information about each video.

1. Why Learn TypeScript?

Is it worth your time to learn TypeScript? Short answer (in my opinion anyway) is YES! In this video I’ll walk through 5 reasons learning TypeScript is worth the effort. Since these videos are intended to be short I could only cover 5, but there are many additional reasons as well!

2. Adding TypeScript to a VS Code Project

How do you get started using TypeScript, writing, and building your code? I’ll walk you through the basics of that process in this video.

3. How to Add WebPack to a TypeScript Project

WebPack’s scary right? Well, truth be told it can be intimidating at times, but it’s pretty easy to use it in TypeScript projects. I’ll walk you through the process in this video.

4. Getting Started with TypeScript Types

It’s no secret that TypeScript adds “strong typing” into your code (they call it TypeScript for a reason). In this video I’ll explain the primitive data types available and show how you can get started using them.

5. Using Classes in TypeScript

Classes are a feature available in JavaScript that can be used to encapsulate your code. They’re not needed for every type of project, but it’s good to know what they’re capable of. In this video I’ll introduce classes and show how they can be used in TypeScript.

6. Using Interfaces in TypeScript

In an earlier video I introduced the concept of TypeScript types. In this video, I walk you through how you can use interfaces to build custom types and explain why you may want to do that. Interfaces are “code contracts” that can be used to describe the “shape” of an object, drive consistency across objects, and more.

7. Using Generics with TypeScript

Generics are “code templates” that can be reused in your code base. In this video I introduce the concept of generics and show simple examples of how they can be used in TypeScript.

Are there more topics that I could have covered? Yep – there’s always more. However, these videos should provide you with a solid starting point to understand core concepts and features. There are a lot of additional resources out there to learn TypeScript (you can start with the docs or the handbook), but I hope these short videos help get you started quickly. I’m personally a huge fan of TypeScript and highly recommend making time to learn it.

If you’d like to dive into more details about TypeScript fundamentals, check out the TypeScript Fundamentals video course on Pluralsight that John Papa and I created.

Migrating a Local Node Script to Azure Functions using VS Code

Dan Wahlin — Fri, 04 Nov 2022 03:48:40 +0000

I have a work project that uses GitHub APIs to access stats about specific repos (views, clones, forks, etc.). It was pretty straightforward to get the project running locally using GitHub’s Octokit REST package and with a little work I had a working Node script that could be run to retrieve the data and display it in the console. That was a good start, but the script functionality needed to be consumed by others in my organization as well as by services such as Power Automate. What to do?

While I could easily convert the script into a Node/Express API and publish it to Azure App Service, I decided to go with Azure Functions since when you boil the script down to the basics, its job is to handle a request and return data. It doesn’t need to be constantly accessed so a consumption based model works well.

Here’s the process I went through to convert my local script to an Azure Function.

1. Install the Azure Functions Extension for VS Code

Creating a Function using VS Code and Extensions

I wanted to develop the Azure Function locally and knew that the Azure Functions extension for VS Code could help with that. It allows you to do everything on your local machine and then publish to Azure Functions once you’re ready.

To get started you can:

Open my project in VS Code.
Install the extension (I already had it installed, but you’ll want it).
Click on Azure in the VS Code sidebar.
Locate the Workspace section and click the + icon.
Select Create Function.

Since I only had a simple Node project at this point, I received the following prompt:

Prompt to create an Azure Functions project.

From there I selected the following:

Language : TypeScript
Trigger : HTTP trigger
Function Name : getGitHubRepoStats
Authorization level : Anonymous

I was prompted to overwrite my existing .gitignore and package.json files. I said “yes” since I only had @octokit/rest in the Node dependencies list. It finished creating the project and displayed the shiny new function in the editor. It added the following into my project (in addition to a few other items):

Files added by the Azure Functions extension.

Good progress! Time to get my existing code converted to an Azure Function.

2. Merge the Local Script Code into the Azure Function

My initial script looked like the following:

const { Octokit } = require("@octokit/rest");
const { v4: uuidv4 } = require('uuid');

// Create personal access token (with repo --> public rights) at https://github.com/settings/tokens
let octokit;
let ownersRepos;
let context;
getStats(context);

async function getStats(ctx) {
    context = ctx || { log: console.log }; // Doing this to simulate what's it like in Azure Functions
    ownersRepos = getRepos();
    context.log(ownersRepos);
    const stats = [];
    for (const repo of ownersRepos) {
        octokit = new Octokit({
            auth: repo.token
        });
        const ownerRepo = {
            owner: repo.owner,
            repo: repo.repo
        }

        const clones = await getClones(ownerRepo);
        const forks = await getTotalForks(ownerRepo);
        const views = await getPageViews(ownerRepo);

        stats.push(getTodayRow(ownerRepo, clones, forks, views));
    }
    context.log(stats);
    return stats;
}

function getRepos() {
    try {
        console.log(context);
        // Need to set env variable GITHUB_REPOS
        // export GITHUB_REPOS="[{ \"owner\": \"microsoft\", \"repo\": \"MicrosoftCloud\", \"token\": \"token_value\" }]"
        const repos = JSON.parse(process.env['GITHUB_REPOS']);
        context.log('Repos:', repos);
        return repos;
    }
    catch (e) {
        context.log(e);
        return [];
    }
}

function getTodayRow(ownerRepo, clones, forks, views) {
    const today = new Date();
    const yesterday = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 1)
      .toISOString().split('T')[0] + 'T00:00:00Z';

    const todayClonesViewsForks ={
        id: uuidv4(),
        timestamp: yesterday,
        owner: ownerRepo.owner,
        repo: ownerRepo.repo,
        clones: 0,
        forks: forks,
        views: 0
    };
    const todayClones = clones.clones.find(c => c.timestamp === yesterday);
    const todayViews = views.views.find(v => v.timestamp === yesterday);
    if (todayClones) {
        todayClonesViewsForks.clones = todayClones.count;
    }
    if (todayViews) {
        todayClonesViewsForks.views = todayViews.count;
    }
    return todayClonesViewsForks;
}

async function getClones(ownerRepo) {
    try {
        // https://docs.github.com/en/rest/metrics/traffic#get-repository-clones
        const { data } = await octokit.rest.repos.getClones(ownerRepo);
        context.log(`${ownerRepo.owner}/${ownerRepo.repo} clones:`, data.count);
        return data;
    }
    catch (e) {
        context.log(`Unable to get clones for ${ownerRepo.owner}/${ownerRepo.repo}. You probably don't have push access.`);
    }
    return 0;
}

async function getTotalForks(ownerRepo) {
    try {
        // https://docs.github.com/en/rest/repos/forks
        const { data } = await octokit.rest.repos.get(ownerRepo);
        const forksCount = (data) ? data.forks_count : 0;
        context.log(`${ownerRepo.owner}/${ownerRepo.repo} forks:`, forksCount);
        return forksCount
    }
    catch (e) {
        context.log(e);
        context.log(`Unable to get forks for ${ownerRepo.owner}/${ownerRepo.repo}. You probably don't have push access.`);
    }
    return 0;
}

async function getPageViews(ownerRepo) {
    try {
        // https://docs.github.com/en/rest/metrics/traffic#get-page-views
        const { data } = await await octokit.rest.repos.getViews(ownerRepo);
        context.log(`${ownerRepo.owner}/${ownerRepo.repo} visits:`, data.count);
        return data;
    }
    catch (e) {
        context.log(`Unable to get page views for ${ownerRepo.owner}/${ownerRepo.repo}. You probably don't have push access.`);
        context.log(e);
    }
    return 0;
}

The next step was to merge my script into the new Azure Function. Since the Azure Functions extension (with my permission) overwrote my package.json file, I ran npm install @octokit/rest to get the package back into the dependencies list.

At this point I had the following function code displayed in VS Code:

import { AzureFunction, Context, HttpRequest } from "@azure/functions"

const httpTrigger: AzureFunction = async function (context: Context, req: HttpRequest): Promise<void> {
    context.log('HTTP trigger function processed a request.');
    const name = (req.query.name || (req.body && req.body.name));
    const responseMessage = name
        ? "Hello, " + name + ". This HTTP triggered function executed successfully."
        : "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response.";

    context.res = {
        // status: 200, /* Defaults to 200 */
        body: responseMessage
    };

};

export default httpTrigger;

Now that I had the shell created for the function, I created a new getStats.ts script in the getGitHubRepoStats function folder, copied in my initial code, and changed require statements to import statements at the top of the file. It looked like the following after finishing a few “tweaks”:

import { Octokit } from '@octokit/rest';
import { v4 as uuidv4 } from 'uuid';

// Create personal access token (with repo --> public rights) at https://github.com/settings/tokens
let octokit: Octokit;
let ownersRepos;
let context;

export async function getStats(ctx) {
    context = ctx || { log: console.log };
    ownersRepos = getRepos();
    const stats = [];
    for (const repo of ownersRepos) {
        octokit = new Octokit({
            auth: repo.token
        });
        const ownerRepo = {
            owner: repo.owner,
            repo: repo.repo
        }
        const clones = await getClones(ownerRepo);
        const forks = await getTotalForks(ownerRepo);
        const views = await getPageViews(ownerRepo);

        const yesterdayRow = getTodayRow(ownerRepo, clones, forks, views);
        stats.push(yesterdayRow);
    }

    return stats;
}

function getRepos() {
    try {
        const repos = JSON.parse(process.env['GITHUB_REPOS']);
        context.log('Repos:', repos);
        return repos;
    }
    catch (e) {
        context.log(e);
        return [];
    }
}

function getTodayRow(ownerRepo, clones, forks, views) {
    const today = new Date();
    const yesterday = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 1)
      .toISOString().split('T')[0] + 'T00:00:00Z';

    const todayClonesViewsForks ={
        id: uuidv4(),
        timestamp: yesterday,
        owner: ownerRepo.owner,
        repo: ownerRepo.repo,
        clones: 0,
        forks: forks,
        views: 0
    };
    const todayClones = clones.clones.find(c => c.timestamp === yesterday);
    const todayViews = views.views.find(v => v.timestamp === yesterday);
    if (todayClones) {
        todayClonesViewsForks.clones = todayClones.count;
    }
    if (todayViews) {
        todayClonesViewsForks.views = todayViews.count;
    }
    return todayClonesViewsForks;
}

async function getClones(ownerRepo) {
    try {
        // https://docs.github.com/en/rest/metrics/traffic#get-repository-clones
        const { data } = await octokit.rest.repos.getClones(ownerRepo);
        context.log(`${ownerRepo.owner}/${ownerRepo.repo} clones:`, data.count);
        return data;
    }
    catch (e) {
        context.log(`Unable to get clones for ${ownerRepo.owner}/${ownerRepo.repo}. You probably don't have push access.`);
    }
    return 0;
}

async function getTotalForks(ownerRepo) {
    try {
        // https://docs.github.com/en/rest/repos/forks
        const { data } = await octokit.rest.repos.get(ownerRepo);
        const forksCount = (data) ? data.forks_count : 0;
        context.log(`${ownerRepo.owner}/${ownerRepo.repo} forks:`, forksCount);
        return forksCount
    }
    catch (e) {
        context.log(e);
        context.log(`Unable to get forks for ${ownerRepo.owner}/${ownerRepo.repo}. You probably don't have push access.`);
    }
    return 0;
}

async function getPageViews(ownerRepo) {
    try {
        // https://docs.github.com/en/rest/metrics/traffic#get-page-views
        const { data } = await await octokit.rest.repos.getViews(ownerRepo);
        context.log(`${ownerRepo.owner}/${ownerRepo.repo} visits:`, data.count);
        return data;
    }
    catch (e) {
        context.log(`Unable to get page views for ${ownerRepo.owner}/${ownerRepo.repo}. You probably don't have push access.`);
        context.log(e);
    }
    return 0;
}

Next, I went into the getGitHubRepoStats/index.ts file, imported the getStats.ts script, and modified the body. Using this approach keeps the function nice and clean.

import { AzureFunction, Context, HttpRequest } from '@azure/functions';
import { getStats } from './getStats';

const httpTrigger: AzureFunction = async function (context: Context, req: HttpRequest): Promise<void> {
    context.log('HTTP trigger function processed a GitHub repo stats request.');
    const stats = await getStats(context);
    context.log("The stats", stats);
    context.res = {
        body: stats
    };
};

export default httpTrigger;

I pressed F5 which then prompted me to install the “core” tools. After the installation completed, it showed several commands in the console, displayed the core tools version, built the code, and launched my new function locally. I hit the http://localhost:7071/api/getGitHubRepoStats URL shown in the console and….drumroll please….it actually worked! Getting projects to work the first time is rare for me so it was nice to have a quick “win” for once.

3. Create a Function App in Azure

Now that the function was working locally it was time to deploy it to Azure. I stopped my debugging session, went to the command pallet (shift+cmd+p on Mac), and selected Azure Functions: Create Function App in Azure.

Using the Azure Functions: Create Function App in Azure Option in VS Code

Once you select that option, you’ll be prompted for:

The Azure subscription to use
The function name
The runtime stack (I selected Node.js 16 LTS)
The region

4. Deploy the Azure Function Code

Once the Azure Function App is created you’ll see a message about viewing the details. The next step is to deploy the code. That can be done by going back to the command pallet in VS Code and selecting Azure Functions: Deploy to Function App. You’ll be asked to select your subscription and Function App name.

Once the function is created in Azure you can go to the Azure extension in VS Code, expand your subscription, expand your Function App, right-click on the function and select Browse Website. Add “/api/” to the URL and if all of the planets align, you should see data returned from your function.

Using the Azure VS Code extension to browser your Azure Functions website

5. Environment Variables and Key Vault

You might have noticed that the function code relies on an environment variable named GITHUB_REPOS. I added that key and value into the Values property of the local.settings.json file which is used when running the function locally (that file isn’t checked into source control).

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "GITHUB_REPOS": "[{ \"owner\": \"microsoft\", \"repo\": \"MicrosoftCloud\", \"token\": \"token-value\" }, { \"owner\": \"microsoft\", \"repo\": \"brainstorm-fluidframework-m365-azure\", \"token\": \"token-value\" }]"
  }
}

I could deploy the function and have the GITHUB_REPOS value show up automatically in the Configuration –> Application Settings section of the Function App (you’ll see that section in the Azure Portal). In my case that wasn’t good enough though. The GITHUB_REPOS value has GitHub personal access tokens in it that are used to make the API calls. I needed a more secure solution when I ran the function in Azure.

To handle that, I created a new Azure Key Vault secret that included the data required for the GITHUB_REPOS environment variable. I then went into Configuration –> Application Settings in the Function App and ensured that it had the following key/value pair:

GITHUB_REPOS=@Microsoft.KeyVault(SecretUri=https://<your_key_vault_name>-vault.vault.azure.net/secrets/<your_secret_name>/)

To get the Function App to successfully talk with Azure Key Vault and retrieve the secret, you’ll also need to create a managed identity. You can find details about that process here.

Conclusion

Migrating a custom script to Azure Functions is a fairly straightforward process especially if you’re able to reuse a lot of your original code. In my case, it allowed me to expose the local script functionality to anyone and any app. While this particular function is publicly accessible, it’s important to mention that you can also secure your functions as needed.

Is that the end of the story? Not for me. I also needed to create a Power Automate flow to consume the data from the function and update a data store. That’s a subject for another post though.

The code shown in this repo can be found here: https://github.com/DanWahlin/github-repo-stats.

What’s Next? The next post in this series titled Use Power Automate to Retrieve Data from an Azure Function for Reporting demonstrates how to automate calling the Azure Function and storing the data.

Use Power Automate to Retrieve Data from an Azure Function for Reporting

Dan Wahlin — Fri, 04 Nov 2022 03:48:04 +0000

In a previous post I showed how to convert a local Node script into an Azure Function so that it can be called from anywhere. While that solution provides a great (and cost effective) way to call the script using HTTP, I also needed to automate the calls and add the data into a spreadsheet for reporting purposes.

This post explores how to automate the process using Power Automate. If you haven’t used Power Automate before it’s part of the Power Platform suite of tools that includes Power Platform, Power Pages, Power Virtual Agents, andPower BI.

Creating a Power Automate Flow

The final version of the automation flow I created looks like the following:

Power Automate Flow

It performs the following steps:

Schedules a task to run every day at a specific time.
Makes an HTTP call to an Azure Function.
Parses the JSON data returned from the function call.
Adds each item from the JSON array to an Excel Online spreadsheet.

To get started, I performed the following steps:

Signed in tohttps://make.powerautomate.com.
Selected my “environment” in the upper-right corner of the screen. You may have multiple environments to choose from if you’re using a work account.
Selected the Create item in the left menu.

From there I chose Scheduled cloud flow from the available templates:

Scheduled flow template

In the dialog that appeared I named my flow, defined how often it would run, and then selected the Create button.

Building a flow based on a schedule

Adding an HTTP Action

After selecting the Create button, Power Automate automatically added the first step of the flow for me. Since I told it to run every day at a specific time, it configured that information for me:

The Recurrence action automatically added by Power Automate

The next step in the flow involves calling the Azure Function to retrieve the data needed for reporting. To make that happen, I clicked the Next step button and typed “http” into the search box. I then selected the HTTP action from the options.

Selecting the HTTP action

NOTE: The HTTP action is a “premium” feature and requires the proper license. While licensing is beyond the scope of this post, you can find more details in this document.

After selecting the HTTP action, you can enter the method and URI that should be used for the API call. My scenario was quite simple:

Method: GET
URI: https://my-azure-function-domain/api/getGitHubRepoStats

The Azure Function for my HTTP call didn’t require authentication (it has publicly available data) so no authentication was needed. Nice and simple. It also didn’t require any specialized headers or queries. In cases where you have to do something more involved, you can learn more about the various options at https://learn.microsoft.com/en-us/power-automate/desktop-flows/actions-reference/web.

Adding the Parse JSON Action

After entering my method and URI into the HTTP action, I needed a way to access the JSON data returned from the Azure Function and parse it. To handle that I selected the New step button, searched for “json”, and selected the Parse JSON action:

Selecting the Parse JSON action

Once the Parse JSON action dialog appeared I performed the following tasks:

Select the Content property and pick Body from the options. I want to parse the body of the message returned from the Azure Function call.
Select the Generate from sample button and enter the JSON returned from the Azure Function call. This automatically generates a schema and adds it to the Schema property of the Parse JSON action. That’s a super nice feature as you’ll see in the next action that’s added.

Generating a schema from JSON data in the Parse JSON action

Adding the Apply to each Action

Up to this point you’ve seen how to call an HTTP API and parse the JSON. The next step is to store the data somewhere which means iterating through the JSON array that’s returned from the API call. To handle that you can use the Control actions provided by Power Automate.

I selected the Next step button again, typed “apply” in the search box, and selected theApply to each action. How did I know to select that? The first time I used Power Automate awhile back I didn’t know, so I had to resort to my favorite search engine. But, once you know about it it’s easy to find and use.

The Apply to each action dialog will ask you to select an output from the previous step. You can select Body from the Parse JSON options in this case since we want to access the JSON object. That gets us to the data we need and will iterate through each object in the array, but how do we add each object into an Excel spreadsheet or some other type of data store?

Adding a Connector

I initially wanted to store my data in something called Dataverse and added a connector to that. However, the person consuming the data wanted it in Excel, so I ended up adding a connector to Excel Online (Business) as well. To do that, I selected the Add an action option from the Apply to each action and selected Excel Online (Business) from the top options that are shown.

Selecting the Excel Online connector

Next, I entered the following values:

Entering information for the Excel Online connector

This uses OneDrive for Business so I selected a spreadsheet that I created there named KR 3 FY23.xlsx as well as the worksheet name (RepoStats in this example). The values I wanted to store from each object found in the JSON array were then picked. Because a schema was created in the previous Parse JSON step, you can pick the JSON properties you want to assign to your Excel columns for each row. That’s the beautify of having the Parse JSON action generate a schema as mentioned earlier.

Validating and Testing the Flow

All of the steps needed for my particular scenario are now defined and we’re ready to validate the flow and test it. That can be done by selecting the Flow checker (to validate) and Test (to try it out) options respectively in the upper-right toolbar:

The Flow checker will display any errors or warnings in the flow so that you can fix them. The Test option allows you to manually start the flow to try it out.

Testing a flow

After testing it, you can go to the test run and if the flow ran successfully you’ll see a message at the top (or an error if it failed):

View the result of a flow run

You can drill down into each action to see the what happened and the data that was involved for each action.

Once the flow was ready to go, I let it run so that the spreadsheet is updated everyday. Someone else within my organization connects to the spreadsheet and brings it into a Power BI dashboard that we can all view.

Conclusion

While I could’ve written a custom app to perform these different steps, by using Power Automate I was able to quickly schedule the functionality I needed and convert the JSON data into rows within Excel all without writing a single line of code. Although this is a fairly straightforward and arguably simple example, it still saved me a ton of time going this route. With more complex flows that time savings is multiplied and there’s the added benefit of giving other people within your organization permissions to edit the flow as well – even if they’re not a developer.

If you haven’t tried out Power Automate, create a free trial and give it a spin. There are infinite tasks that can be automated using it!

Simplifying Front-End State Management with Observable Store

Dan Wahlin — Thu, 21 Mar 2019 22:47:35 +0000

I admit it - I think the use of some front-end JavaScript state management patterns has gotten out of control. When you’re spending a significant amount of time writing code (and often a lot of it) to handle application state or relying on a scaffolding tool that generates 100s or even 1000s of lines of code then it’s time to take a step back and ask, “Do I really need all of this?”. While you’re at it you might also ask, “What can I do to simplify my code and bring some sanity back to it?”.

Rather than ranting about my views on keeping software simple, choosing the right tool for the right job, the importance of considering maintenance costs, challenges that more complex patterns present when contractors or new hires are involved, and more, let me get right to the point:

I think front-end state management needs a big dose of simplicity!

After hearing from many people and working on projects myself, I was frustrated with some of the state management options out there and decided to experiment with a simple solution that eventually became a project I call Observable Store. It turns out several people had a similar idea which was refreshing to see (there are a few similarly named projects on Github and npm).

Note: If you want my more opinionated view on state management complexity you can jump down to My Two Cents on State Management Complexity in this post.

The Birth of Observable Store

One of the perks of my job is that I get to work with a lot of developers at companies around the world. This comes in the form of architecture work, training, mentoring, talking with people at conferences, meetups, webinars, and more. I’ve had many conversations about various state management options and listened to stories about what has worked and what hasn’t. One common comment I’ve continually heard is, “I wish there was a more simple way to handle state management in my front-end apps”.

As I’ve talked one on one with other architects and developers, helped people with their projects, and worked on my own, I’ve often asked, “What is it that you really want in a state management solution?”. Here are main goals that came out of asking that question:

Single source of truth
State is read-only/immutable
Provide state change notifications to any subscriber
Track state change history
Minimal amount of code required
Works with any front-end library/framework (Angular, React, Vue.js, or anything else that supports JavaScript)

I started playing around with adding these general goals/concepts into a simple library about 1 1/2 years ago and ultimately developed something I now call Observable Store. I use it for any front-end projects I work on (React, Vue.js, Angular or others) that need a state management solution. Observable Store satisfies the goals mentioned above but does so in an extremely simple way. The code for the library is only around 220 lines total since the “power” it provides comes from using RxJS Subjects and Observables. In fact, Observable Store only has 1 dependency – RxJS.

So why consider Observable Store? If you’re interested in achieving any of the goals shown earlier then Observable Store provides an extremely simple way to achieve those goals. You instantly get a single store that can be referenced throughout your app, state that is immutable (good for change detection in libraries/frameworks), state history tracking, and a way to subscribe to store changes. Plus, Observable Store can be used with any JavaScript library or framework. You’re not locked into anything – except using JavaScript.

So how do you get started with Observable Store? Here’s a quick overview.

Getting Started with Observable Store

To get started with observable store you simply npm install it in your project (Angular, React, Vue.js, or any JavaScript project):

    npm install @codewithdan/observable-store

From there you create a service class that extends ObservableStore. If you’re working with TypeScript you can use a generic to pass the shape of the data that gets stored in the store (pass a class or interface). TypeScript isn’t required though and it works fine with ES2015 (or even ES5) as well.

    // Optionally define what gets stored in the observable store
    export interface StoreState {
        customers: Customer[];
        selectedCustomer: Customer;
        orders: Order[];
        selectedOrder: Order;
    }

    // Extend ObservableStore and optionally pass the store state
    // using TypeScript generics (TypeScript isn't required though)
    export class CustomersService extends ObservableStore<StoreState> {
      constructor() {
        // Pass initial store state (if desired). Want to track all
        // changes to the store? Set trackStateHistory to true.
        super(initialStoreState, { trackStateHistory: true });
      }
    }

Now add any functions to your class to retrieve data from a data store and work with the data. Call setState() to set the state in the store or getState() to retrieve state from the store. When setting the state you can pass an action name which is useful when tracking state changes and state history.

    import { Observable, of } from 'rxjs';
    import { ObservableStore } from '@codewithdan/observable-store';

    export class CustomersService extends ObservableStore<StoreState> {
        constructor() { 
            const initialState = {
                customers: [],
                selectedCustomer: null,
                orders: Order[],
                selectedOrder: null
            }
            super(initialState, { trackStateHistory: true });
        }

        get() {
            // Get state from store
            const customers = this.getState().customers;
            if (customers) {
                // Return RxJS Observable
                return of(customers);
            }
            else {
                // call server and get data
                // assume async call here that returns Observable
                return asyncData;
            }
        }

        add(customer: Customer) {
            // Get state from store
            let state = this.getState();
            state.customers.push(customer);
            // Set state in store
            this.setState({ customers: state.customers }, 
                          'add_customer');
        }

        remove() {
            // Get state from store
            let state = this.getState();
            state.customers.splice(state.customers.length - 1, 1);
            // Set state in store
            this.setState({ customers: state.customers } 
                          'remove_customer');
        }

    }

As the store state changes, any part of the application can be notified by subscribing to the store’s stateChanged event. In this example changes made to the store by CustomersService will be received which provides a nice way to listen to a “slice” of the overall store quite easily.


    // Subscribe to the changes made to the store by 
    // CustomersService. Note that you'll want to unsubscribe
    // when done.
    this.customersService.stateChanged.subscribe(state => {
      this.customers = state.customers;
    });

Note that because the store state is immutable, a stateChanged subscriber will always get a “fresh” object back which works well with detecting state/data changes across libraries/frameworks. Because RxJS observables are used behind the scenes you can use all of the great operators that RxJS provides as well.

If you need to listen to all changes made to the store you can use the globalStateChanged event (thanks to Mickey Puri for this contribution):


    // Subscribe to all store changes, not just the ones triggered
    // by CustomersService
    this.customersService.globalStateChanged.subscribe(state => {
      // access anything currently in the store here
    });

You can even listen to a specific slice of the store (customers and orders for example) by supplying a stateSliceSelector function.

To handle orders, you can create another class that extends ObservableStore and add the order related functionality in it. By breaking the functionality out into separate classes you can achieve single responsibility (the “S” in SOLID) while still having only one store backing the entire application.

    // Extend ObservableStore
    export class OrdersService extends ObservableStore<StoreState> {
      constructor() {
        // Define that we want to track changes that this object
        // makes to the store
        super({ trackStateHistory: true });
      }
    }

Both CustomersService and OrdersService share the same store (as do all classes that extend ObservableStore in your application).

The Observable Store API and settings are simple to learn and you can get it up and running in no time at all. You can find examples of using it with Angular and React apps (I’m hoping to add a Vue.js example in the near future) in the Github repo.

Is Observable Store the answer to keeping state management simple in front-end applications? It’s one potential solution that has worked well for my company and several other companies/developers who are using it. I’ve been using it privately for over a year now and really enjoy the simplicity it brings to the table. If you try it out or have questions about it feel free to leave a comment below or in the Github repo.

My Two Cents on State Management Complexity

I mentioned toward the beginning of this post that I didn’t want to get into “my” opinion on state management since I prefer to focus on potential solutions rather than focusing on problems. I’m just one guy after all that has an opinion that some may agree with and some definitely will disagree with. Having said that, many people ask my opinion about this particular subject so here’s a quick summary of where I stand.

I think we often get caught up in the “group think” mode of developing software (something that I’m guilty of as well on occasion) and that results in great things and a lot of not so great things spreading like fire across the developer community. Because a concept or pattern is “popular” or “everyone is using it” we gravitate to it without digging in and considering if it’s the best way to go for our specific application scenario, if it’s actually necessary, and the pros/cons it brings to the team or project. It feels like a “sheep off the cliff” mentality in some cases. I recently came across a post that echos a lot of my thoughts on the “state” of front-end state management complexity.

As I’ve worked with various companies around the world over the years, talked with developers at conferences, and interacted with people online, one of the main “gripes” I keep hearing can be summed up as, “Front-end state management complexity is killing us!”. I also hear, “I can’t believe how much code is added to our application to follow pattern X”, or “We’re using technology X and Y at work across teams and can’t share our state management code between them!”.

In all fairness, some of the patterns that are available like Redux provide a lot of value. For example, consistency for a team, insight into the flow of data, better debugging in some cases, and more. I don’t think there’s any dispute there so I want to make that clear. Many people are using some of the different font-end state management patterns very successfully especially with larger teams and a lot of moving parts. So what’s the problem?

For starters, if everyone on a team doesn’t understand a given pattern well, then they’re copying and pasting code or using some type of scaffolding tool without really understanding what’s going on and why they’re doing it. As the application’s complexity grows they feel more and more lost. This often applies to projects that bring in contractors, new hires, or developers that may not work solely in the front-end world. But, it applies to pure front-end developers too I’ve found.

An argument can be made that anyone using a pattern without really understanding it needs to take time to learn the pattern better, and I think that’s a valid point. But, when someone didn’t choose the pattern used in a project and deadlines are looming, they don’t have much of a choice but to push through it even if they don’t fully understand what’s going on. Plus, I think there’s also an argument to be made that if a pattern requires that much time and code to learn then maybe it’s worth considering if it’s the best way to go in the first place? Keep in mind I’m only talking about state management here. We still have the rest of the application to worry about as well.

In addition to understanding a pattern well, can you use the same code between different front-end JavaScript technologies and does the code look the same? For example, React has Redux, Angular has NgRx (Redux + RxJS), Vue.js has Vuex, and so on. That may not be an issue for you, but it is for several companies I work with because they don’t want to maintain different implementations of the same overall pattern.

For the question, “Can you use the same code between different front-end JavaScript technologies?”, I’m going to say the answer to that is a definite “No!” – sharing state management code often isn’t an option in the majority of scenarios I’ve seen. The pattern used may be similar in some cases, but the implementations are radically different between libraries/frameworks. If your company isn’t using just one main library/framework for front-end projects that can present a challenge when you’re trying to make projects as consistent as possible (while also letting developers use the technology they prefer).

There are certainly additional challenges that I can point out with more complex state management options (maintenance challenges, the sheer amount of code added, bundle sizes, team knowledge, etc.) but that’ll do for now. I think it really boils down to using the right tool for the right job and realizing that not everything is a nail that requires a complex hammer.

I think it really boils down to using the right tool for the right job and realizing that not everything is a nail that requires a complex hammer.

Isn’t it worth considering if the state management pattern itself (whatever it is) may actually be overly complex for a given scenario and that viable alternatives may exist? One size NEVER fits all and there are many applications out there using a complex state management pattern that simply don’t need it at all. I’ve seen it myself many times at companies. For example, an application may perform standard CRUD (Create, Read, Update, Delete) operations directly to a back-end service. Once an operation is complete it’s done. Aside from showing a message to the user there’s nothing else to do from a state perspective. In this simple scenario and many others there’s often no need for a complex state management solution – it would only add unnecessary complexity. Which brings me to 3 of my favorite words: “keep it simple”.

Keep it Simple!

I truly admire architects and developers that have the wisdom, knowledge, expertise, and ability to keep their application code as simple as possible while still meeting the needs of users. Building good software is hard, and the ability to keep code simple is arguably just as hard. It’s an art and skill that has to be developed over time and in some cases I feel like that skill has been lost. Keeping things as simple as possible yields many positive results in the end – especially when it comes to long-term maintenance.

This is definitely one of those highly subjective topics I realize, but let me know your *constructive* thoughts on it in the comments. Every situation is different so I’m always interested in hearing different opinions. You can reach out to me on Twitter as well.

Originally posted at https://blog.codewithdan.com