Azure Static Web Apps Login Redirects: How to Stop It

Overview

Integrating custom Microsoft Entra ID (Azure AD) authentication with an Azure Static Web App (SWA) on the Standard tier should be straightforward, but subtle misconfigurations can lead to a frustrating infinite redirect loop.

Typically, you log in, complete MFA, and watch the browser bounce repeatedly between Entra ID and your application until Microsoft halts the flow with Error 50074 (“We couldn’t sign you in”). When you check /.auth/me, you find that clientPrincipal is null.

Azure Static Web Apps Login Redirects: How to Stop It

Here is a breakdown of why this happens and the exact checklist to fix it.

---

The Problem: Why Does the App Loop?

The infinite loop occurs when the interactive user login succeeds in Entra ID, but SWA’s backend proxy fails the subsequent token exchange.

When the token exchange fails:

• 1. SWA cannot establish the StaticWebAppsAuthCookie.
• 2. The user lands back on the app unauthenticated (clientPrincipal: null).
• 3. SWA evaluates the catch-all route guard (/*), issues a 401, and responseOverrides immediately redirects the user back to /.auth/login/aad.
• 4. The cycle repeats until Entra ID detects the loop and blocks access.

Two common triggers for this failure are explicitly passing OAuth parameters (like response_type=code or scope) inside login.loginParameters—which breaks SWA’s built-in token negotiation—and using internal rewrite rules instead of explicit redirect routes.

---

What to Check

• SWA Hosting Plan: Ensure your Azure Static Web App is running on the Standard SKU. Custom OpenID Connect / Entra ID identity providers are ignored on the Free tier.
• Platform Type: Configured strictly as Web (not Single-page application) under App registrations > Authentication.
• Redirect URI: Registered under the Web platform as https://<your-domain>/.auth/login/aad/callback.
• ID Tokens Enabled: In Entra ID > Authentication > Platform configurations > Web > Implicit grant and hybrid flows, ensure the checkbox for ID tokens (used for implicit and hybrid flows) is enabled.
• OpenID Issuer Tenant ID: The openIdIssuer URL must use your actual Directory (Tenant) ID (not an Azure Subscription ID), ending with /v2.0 and no trailing slash.
• Client ID Setting: The Application (Client) ID matches the exact environment variable name referenced in clientIdSettingName.
• Client Secret Value: The SWA configuration setting referenced by clientSecretSettingName must hold the Secret Value (the plaintext string generated on creation), not the Secret ID GUID.
• No loginParameters Overrides: Omit login.loginParameters entirely from your JSON config. Do not manually pass response_type or scope, as SWA handles Authorization Code negotiation out of the box.
• Route Actions: Set the /login route to an explicit redirect with post_login_redirect_uri=/ rather than an internal rewrite to /.auth/login/aad.
• Clean System Endpoints: Do not define custom route rules in routes for SWA system paths like /.auth/login/aad/callback or /.auth/complete.

---

Working staticwebapp.config.json Baseline

Use this base configuration to validate that the login process works properly. You can then make additional changes for your configuration.

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET"
        }
      }
    }
  },
  "routes": [
    {
      "route": "/login",
      "redirect": "/.auth/login/aad?post_login_redirect_uri=/",
      "statusCode": 302
    },
    {
      "route": "/logout",
      "redirect": "/.auth/logout?post_logout_redirect_uri=/",
      "statusCode": 302
    },
    {
      "route": "/*",
      "allowedRoles": ["authenticated"]
    }
  ],
  "responseOverrides": {
    "401": {
      "redirect": "/.auth/login/aad?post_login_redirect_uri=/",
      "statusCode": 302
    }
  }
}

---

🌟 Let’s Connect & Build Together

Thanks for reading! 😊 If you enjoyed these resources, let’s stay in touch! I share deep-dives into AI/ML patterns and host community events here:

• GDG Broward: Join our local dev community for meetups and workshops.
• Global AI Events: Join Global AI Events.
• LinkedIn: Let’s connect professionally! I share insights on engineering.
• GitHub: Follow my open-source journey and star the repos you find useful.
• YouTube: Watch step-by-step tutorials on the projects listed above.
• BlueSky / X / Twitter: Daily tech updates and quick engineering tips.

👉 Originally published at ozkary.com

Overview Integrating custom Microsoft Entra ID (Azure AD) authentication with an Azure Static Web App (SWA) on the Standard tier should be ...

Read Article →

React Suspense Fallback Keeps Rendering When Using Lazy-Loaded Routes

When a React application is loading a new lazy-loaded route or a component, it is a common practice to show a loading component with an animation to provide feedback to the user. In React, we use the Suspense component to handle this scenario, but there are times when the fallback component never unloads, and it keeps rendering on the browser.

When a Suspense fallback component never unloads, it is because there must be a child component that keeps rendering. This causes the Suspense component to continue to run, thinking that a child component in still in suspense or loading state.  This gives us the wrong sense that the Suspense component is misbehaving, when it is in fact the child components that is at fault. For a deeper understanding, let’s take a look at a real example.

Suspense with Declarative Routes

To demonstrate this problem, let’s first take a look at an implementation of a React application that loads some route information in a declarative approach, which is simple enough and does not introduce any rendering problems. We should also notice how the components are lazy-loaded to help us do code splitting for performance improvements on the load time and enable us to trigger the Suspense component automatically.

👍 This is a typical approach when creating apps with a simple routing structure.

Suspense with a Router Component

Let’s now take a look at a more complex scenario where we need to load the route information from a JSON configuration file. This introduces a variation on the process by adding the routes using a function. 

This code change introduces new behavior, and it causes the component to re-render multiple times. We can trace that by adding a console.log operation before returning the content. If we look at the browser console, we should see the output of our console.log call. From the application standpoint, this behavior is noticeable because the fallback component continues to show on the browser as the Suspense component does not detect that the child component is done rendering. Now that we understand the problem, how should we correct it?

👍 A child component continues to be in suspense until it stops rendering.

Adding State Management

To correct this behavior, we should clearly understand the root cause. Since we introduce a dynamic way to load the routes, the component has no way to understand its current state. It only knows that some data is being loaded every time it calls the function, and the data seems new or different. To avoid this, we need to add state management to the component, which is a React best practice when writing data driven components. Let’s refactor our code to see how state management can make a difference.

By looking at our new implementation, we can see that the route collection is now managed in a state variable. We also use an useEffect hook to load the data. This enables us to initiate the state of the component with some valid data. We also track the route collection as a dependency, and since there are no changes to the data, the state does not change, and the component completes its suspense state thus allowing the app to complete its rendering process.

Conclusion

The React Suspense component is a great feature to provide feedback to users while a component is rendering. When we add dynamic data to the application, we should understand that this impacts the state management process, which is used to signal when a component is in a suspense state. Depending on how nested your components are, a child component can continue to render, causing the Suspense fallback UI to continue to load non-stop. 

👍 To diagnose a component, you can add a suspense component around it, and we should notice only that component content to continue to use the suspense fallback animation.

Thanks for reading.

Send question or comment at Twitter @ozkary

Originally published by ozkary.com

When a React application is loading a new lazy-loaded route or a component, it is a common practice to show a loading component with an anim...

Read Article →

Create API Mocks with Azure APIM and Postman Echo Service

When kicking off a new API integration project, we often star by getting the technical specifications on the external API. The specifications should often come in the form of an OpenAPI Specification or a JSON schema definition. It is often the case, that the external API may not be available for the implementation effort to start. This however should not block our development effort because we can create API mocks without much development effort. The mocks can echo back our original request with the same JSON document model or with some modifications.

We are going to work on a simple telemetry digest API and see how we can create a mock. But before, we look at the solution, let’s review some important concepts. This should help us have more background on what we are trying to achieve and understand the tooling that we are using.

What is OpenAPI Specifications

The OpenAPI Specifications (OAS) is a technical standard for defining RESTful API in a declarative document, which allows us to clearly understand the contract definitions, and the operations that are available on that service. The OpenAPI Specification was formerly known as the Swagger Specifications, but it has been adapted as a technical standard, and it was renamed.

The specification is often written using YAML, which is a human-readable text file that is heavily used on infrastructure configuration and deployments. In our case, we will be using this following YAML, to understand a simple service.

👍 Use Swagger.io to create an OpenAPI specificastion doument like the one above.

What is Postman and the Echo APIs

Postman is a development tool that enables developers to test APIs without having to do any implementation work. This is a great approach as it enables the development team to test the API and clearly understand the technical specifications around security and contract definitions.

Postman provides several services. There is a client application that should be used to create a portfolio of API requests. There is also an ECHO API service that enables team to create mocks by sending the request to that service, which, in turn, echoes back the request with additional information.

When an external API is not available, we can use the ECHO API to send our HTTP operations to quickly create realistic mocks for our implementation effort as this integrates with external services, and we can make changes to the JSON response to mock our technical specifications.

👍 Note:  Use https://postman-echo.com/post for the Echo API

 

What is Azure API Management

The Azure API Management service is a reverse proxy gateway that manages the integration of APIs by providing the routing services, security and other infrastructure and governance resources.  It provides the management of cross-cutting concerns like security policies, routing, document (XML, JSON) transformation, logging in addition to other features.

For our purpose, we can use the YAML specification that was previously defined to create a new API definition, as this is supported by Azure APIM. By importing this document, a new API is provisioned with the default domain (or custom domain for production environments) on the service plus the API routing suffix and version, which defines the RESTful route on the URL. An example of this would be:

api-ozkary.azure-api.net/telemetry/v1/mock

In the lifecycle of every request, APIM enable us to inspect the incoming request, forward the request to a backend or external service and inspect or transforms the outbound response back to the client application. The inbound and outbound process are the steps in the API request lifecycle that we can leverage to create our API mocks.

Look at a Simple API Use Case

We can now move forward to talk about our particular use case. By looking at the YAML document, we can see that our API is for a simple telemetry digest that we should send to an external API.

Each telemetry record should be treated as a new record; therefore, the operation should be an HTTP POST. As the external service processed the request, the same document should be returned to the client application with the HTTP status code of 201, which means that the record was created.

For our case, the Postman Echo API adds additional data elements to our document. Those elements are not needed for our real implementation, so we will need to apply a document transformation on the outbound steps of the request lifecycle to return a document that meets our technical specifications.

As you can see on the image below, the response from the Postman echo service returns our request data in the data property, but it also adds other information which may not be relevant to our project.

Create a Mock to Echo the Requests

Once the YAML is imported into Azure APIM, we can edit the API policies from the portal. To mock our simple telemetry digest, we need to add policies to both the inbound and outbound processing steps. The inbound step is used to change the inbound request parameters, headers and even the document format.  In this case, we need to change the backend service using the set-backend-service policy and send the request to the postman-echo.com API. We also need to rewrite the URI using the rewrite-uri policy and remove the API URL prefix. Otherwise, that will be appended automatically to our request to the Echo API, which will cause a 404 not found HTTP error.

When the response comes back from the Echo API, we need to transform the document in the outbound processing step. In this case, we need to serialize the body of the response, read the data property, which holds the original request, and return only that part of the document. For this simple implementation, we are using a C# script to do that. We could also use a liquid template to do something similar. Liquid templates provide a declarative way to transform the JSON response. It is a recommended approach when we need to rename properties and shape the document differently, which in some cases can get very complex. When using the C# code approach the code can get very hard to maintain.

👍 Note: The C# capabilities on Azure API are very limited. When applicable, the use of liquid templates is recommended.

Conclusion

With every new integration project, there is often the need to mock the APIs, so the implementation effort can get going. There is no need to create some API mock project that requires a light implementation and some deployment activities. Instead, we can use Azure API Management and Postman echo APIs to orchestrate our API mocks. By taking this approach, we accelerate and unblock our development efforts using enterprise quality tooling.

Thanks for reading.

Send question or comment at Twitter @ozkary

Originally published by ozkary.com

When kicking off a new API integration project, we often star by getting the technical specifications on the external API. The specification...

Read Article →

Improve User Experience with React Code Splitting and Lazy Loading Routes

When building single page applications, SPA. The application load time performance is very important as this improves the user experience. As development teams mostly focus on functional requirements, there is a tendency to skip some of the non-function requirements like performance improvements. The result is that when a web application is loaded, all the resources including views that are not visible on the home page are downloaded in a single bundle. This is referred as eagerly loading, and this approach often causes a slow load time as all the resources need to be downloaded before the user can interact with the application.

To avoid this performance issue, we want to only load the resources that are needed at the time that the user is requesting it, on demand. As an example, only load the resources for the home page without loading other page resources, thus improving the load time. This is usually called lazy loading. To support this, we need to load chunks of the application on demand.  A chunk is basically a JavaScript or CSS file that packages only the containers, components and dependencies that are needed for that view to render.

To lazy load the different views for an application, we need to implement the concept of Code Splitting, which basically enables us to split the code bundle into chunks, so each container view and dependencies can be downloaded only as the user is requesting it. This greatly improves the app performance because the chunk size is small compared to the entire code bundle.

Importing Container Views and Routing

A simple yet very important approach to improve load time performance is to lazy load the routes. This is a code split process, which breaks down each container view into a separate chunk. In addition, components within these containers can also be lazy loaded to break down further the size of each chunk.

To get started, let’s look at what the navigation configuration of React application looks like, so we can review what takes place when a user loads the application.

In this example, we should notice that our React app has three main containers, which are basically the pages or views that the user can load from the app.  These containers are usually in the container folders of the project file structure. This path is important because it is needed to associate them to a route.

👍 Pro Tip: It is a best practice to plan your folder structure and create a folder for each container, components, elements, and services.

To loads those views, we need to import them and map them to an application route. This should be done on the application starting point, which should be the App.tsx file. The code to do that looks like this:

In this code, we are using the import directives to load each container view. Each of those views is then mapped to an application route directive. When using import directives, there is no optimization, so we should expect that when this app loads on the browser, all the views should be loaded in a single bundle. To clearly see this, let’s use the browser dev tools to inspect how this look at the network level.

By doing a network inspection, we can see that there is a bundle.js file. This file has a 409kb size. In the example of a simple app, this is not bad at all, but for real world apps, this bundle size may be much bigger than that, and eventually it impacts the load time. A benefit of using a single bundle is that there are no additional trips to download other file chunks, but this approach will not let your application scale and perform acceptably over time.

Lazy Loading Container Views

Now, we should be able to understand that as the app continuous to grow, there is potential performance challenge, so the question is how can be optimized the loading of our application? The simple answer is that we need to Code Split the bundle into smaller chunks. A quick approach is to Lazy Loading the routes. This should enable us to improve the load time with very small code changes. Let modify our previous code and look at the performance difference.

In the updated version of our code, we are now using the lazy direct to delay the import of the container view only when the user requests that route. The rest of the code remains the same because we are still using the same container references and mapping them to a route. OK, let’s run the app and do another network inspection, so we can really understand the improvement.

In this last trace, we can see there still a bundle file with roughly the same size of the file as before. This bundle file contains the optimization code to map a route to a particular bundle chunk. When a particular route is loaded, home route is loaded by default, the chunk for that view is downloaded, notice the src_container_Home_index_tsx.chunk.js. As the user navigates to other routes, the additional chunks are downloaded on demand, notice the Analytics and Admin chunks.

Final Thoughts

With this simple app, we may not be able to truly appreciate the optimization that has been done by just deciding to lazy load the containers. However, in real-world applications, the size of a single bundle will quickly get big enough to impact the usability of the application as users will have to wait a few or several seconds before the app is clickable. This is referred to as Load Time.

In addition, build tools for framework like React show performance warnings when loading the application in the development environment, as it tracks some performance indicators like load time. Also, it is a good practice to use a tool like Lighthouse, in the browser dev tools, to run a report and measure performance indicators like load time, render time and others.

👍 Pro Tip: Always use a performance tool to measure performance and other industry best practices for web applications.

With a bit of performance planning, we can feel confident that we are building an app that will scale and perform as additional business requirements are added, and the app will provide a much better user experience by improving the overall load time.

Send questions or comments at Twitter @ozkary

Originally published by ozkary.com

When building single page applications, SPA. The application load time performance is very important as this improves the user experience. A...

Read Article →

Reduce code complexity by letting an API Gateway handle disparate services and document transformation

Modern Web applications use the microservice architecture for their API service integration. These APIs are often a combination of internal and external systems. When the system is internal, there is better control of the API endpoints and contract payload which the front-end components consume.  When there are external systems, there is no real control as the endpoints and contracts can change with new version updates.

There are also cases when the integration to these external integrations must be done with multiple providers to have some redundancy. Having to integrate with multiple providers, forces the application to manage different endpoints and contracts that have different structure. For these cases, how does the client application know what API endpoint to call? How does it manage the different structure and formats, JSON or XML, on both the request and response contracts? What is the approach when a new external service is introduced? Those are concerning questions that an API Gateway can help manage.

What is an API Gateway?

An API Gateway is an enterprise cloud solution that integrates client applications to back-end services or APIs. It works as a reverse proxy which forwards inbound requests to internal or external services. This approach abstracts the service's endpoint details from the application; therefore, an application only needs to be aware of the gateway endpoint information.  

When dealing with disparate services, an application must deal with the different contracts and formats, JSON, XML, for the request and subsequent response. Having code on the application to manage those contracts, leads to unmanageable and complex transformation code. A gateway provides transformation policies that enables the client application to only send and receive one contract format for each operation. The gateway transformation pipeline processes the request and maps it to the contract schema required by the service. The same takes place with the response, as the payload is also transformed into the schema expected by the client application. This isolates all the transformation process in the gateway and removes that concern from the client.

API Settings

To better understand how an API Gateway can help our apps avoid a direct connection to the services, we should learn about how those services and their operations should be configured.  To help us illustrate this, let’s think of an integration with two disparate providers, as shown on the image below.

The client apps can be using the APIs from either Provider A or B. Both providers are externally located in a different domain, so to manage the endpoint information, the apps are only aware of the gateway base URL.  This means that independently of how many providers we may add to this topology, the clients always connect to the same endpoint.  But wait, this still leaves us with an open question. How is the routing to a specific provider handled?

Operation Routing

Once we have the base URL for the gateway endpoint, we need to specify the routing to the API and specific operation. To set that, we first need to add an API definition to the gateway. The API definition enables us to add an API suffix to the base URL. This suffix is part of the endpoint route information and precedes the operation route information.

An API definition is not complete unless we add the operations or web actions which handle the request/response. An operation defines the resource name, HTTP method and route information that the client application uses to call the API endpoint in the gateway. Each route maps to an operation pipeline which forward requests to the provider’s API endpoint and then sends the response back to the client. In our example, the routing for the operation of Provider A looks as follows:

This image shows us how an API has a prefix as well as operations. Each of the operations is a route entry which completes the operation URL path. This information, plus the base URL, put together handles the routing of a client request to a particular operation pipeline, which runs a series of steps to transform the documents and forward the request to the provider’s operation.

Note: By naming the operations the same within each API, only the API suffix should change. From the application standpoint, this is a configuration update via a push update or a function proxy configuration update.

Operation Pipeline

The operation pipeline is a meta-data driven workflow. It is responsible for managing the mapping of the routing information and execution of the transformation policies for both the request and response. The pipeline has four main steps: Frontend, Inbound, Backend and Outbound.

The Frontend steps handles the Open API specifications JSON document. It defines the hostname, HTTP schemes, and security requirements for the API. It also defines, for each operation, the API route, HTTP method, request parameters or model schema for both the request and response. The models are the JSON contracts that the client application sends and receives.

The Inbound step runs the transformation policies. This includes adding header information, rewrites the URL to change the operation route into the route for the external API. It also handles the transformation of the operation request model into the JSON or XML document for the external API. As an example, this is the step that transform a JSON payload into SOAP by adding the SOAPAction header and SOAP envelope into the request.

The Backend step defines the base URL for the target HTTP endpoint. Each operation route is appended to the backend base URL to send the request to the provider. On this step, security credentials or certificated can be added.

Lastly, the Outbound step, like the Inbound step, handles header and document transformation before the response is sent back to the client application. It transforms the JSON or XML payload into the JSON model defined by the Frontend schema configuration. This also the place to add error handling document standards for the application to handle and log accordingly independently of the provider.

This is an example of a transformation policy which shows an inbound request transformed to SOAP and outbound response transformed to JSON.

Conclusion

In Microservice architecture, a client application can be introduced to disparate APIs which support multiple document structure and different endpoints, as these API services are hosted in different domains. To avoid complex code which deal with multiple document formats and endpoints, an API Gateway can be used instead. This enables us to use meta-data driven pipelines to manage that complexity away from the app. This should enable the development teams to focus on app design and functional programming instead of writing code to manage infrastructure concerns.

Have you faced this challenge before, and if so, what did you do to resolve it? If you use code in your app, what did you learn from that experience?

Send question or comment at Twitter @ozkary

Originally published by ozkary.com

Modern Web applications use the microservice architecture for their API service integration. These APIs are often a combination of intern...

Read Article →

Static Web Apps SPA Handle 404 Page Not Found

Single Page Applications (SPA) handle the client-side routing or navigation of pages without the need to send a post back or request to the server hosting the application. To enable the client-side routing, applications build using React or Angular and others bundle the application for a single download of all the page resources. This bundle download allows the routing service to load the next view container and components when the user selects a new page, essentially loading a new route, without having to make a request. Depending on the size of the application, this approach can lead to initial slow load time on the browser.

To address the initial slow load time, a build optimization can be done that can enable the loading of the content associated with a route to be done on demand, which requires a request be sent to the server. The optimization is handled by using a lazy loading approach, in which the route content is downloaded as an application chunk from the hosting environment. This means that instead of downloading the entire app during the initial download, only an index of URLs pointing to chunk files that are associated to the route is downloaded. This can also include chunk files for CSS, JS and even image downloads. As a route is loaded, the index lookup provides the URL of the chunk to download, thus making the app load faster. When another route is loaded, a new chunk is downloaded.

Client-Side vs Server-Side Routing

The client-side routing works as designed when the navigation operations are done normally by the user clicking on menu options or call-to-action buttons.  In some cases, a user may have to reload or refresh the web application. This action forces the browser to make a request to the server.  Once the request makes to the server, the server-side routing rules are applied. If the server routes definitions do not have a handler for all the routes defined on the client-side, the server fails to find the content that is requested and responds with an HTTP 404 error, which means that a page is not found.

By default, the server-side routing knows to always return the index page hosting the SPA.  This is usually mapped to the root of the domain or / path. However, when a user starts to navigate the app, the routes change to match a different path. For the server to be able to understand what to send back when this new path is loaded, we need to configure the server in a way that it knows to return the index page for all the routes, not just the root path. For Static Web Apps (SWA) which are hosted on CDN resources, this is done using a configuration setting for the application. These settings enable the configuration of the routing and security policy for the application. Let’s use an example to review that in more detail.

Static Web Apps Settings

Imagine that we have an SPA app with the following client-site route configuration:

The above routing information is typical of an app that has a home, about and contact page. The SPA provides the navigation elements or call-to-action buttons, so the user can select any of those pages.  When the user is on the home page which is defined by the home route or /, a page reload does not cause any problem as this path is usually associated to the index page of the application on the server routing configuration.

When the user navigates to the other route locations, for example /about, a page reloads sends a post back to the server, and if there is no handling for that page the 404 error is created. Depending on the hosting resource, the 404 page can be system generated, which takes the user away from the application experience altogether.

To manage this concern, the latest release of SWA provides the staticwepapps.config.json file. This file is required to be able to configure the server-side route and security information for the app. It is also used to override the behavior of some HTTP operations, as well as configuring HTTP responses. For the scope of this conversation, we focus on the routing configuration only.

Note: At the time of this writing, the routes.json file has been deprecated for the staticwebapps.config.json. The configuration between these files has some differences, so carefully review the options being used, just renaming routes.json will lead to problems on the application behavior.

Routing and Response Overrides

The routes' configuration enables us to add server-side routing rules with security, for authentication and authorization requirements, as well redirect rules for a request.  To avoid the 404 error, the SWA configuration should have an entry for every client-side route configuration. For our specific example, this means that we should add the routes for the /about and /contact-us route. This is done by adding route entries in the routes' collection, as shown below:

"routes": [     {       "route": "/",       "allowedRoles": ["anonymous"]     }, {       "route": "/about",       "allowedRoles": ["anonymous"]     },  {       "route": "/contact-us",       "allowedRoles": ["anonymous"]     } ],

The routes on the server-side configuration lists all the client-side configuration and add a security role to enable anonymous users to access the route.  

Do We Need to Map All the Routes?

We do not only if we use a fallback policy. Our routing configuration only has three separate routes, and thus it is simple to manage. This however is not reflective of a complex app which can have several route entries. In addition, having to add every single client-side entry on the server is error-prone, as a route can be configured improperly or just forgotten to be included.

The Static Web App team also figure as much, so a fallback setting was introduced on more recent releases. This setting allows the server configuration to “fallback” to the default route when a route is not defined. This works just as good because for SPA, we always want the index page to be sent to the client. As the page is loaded on the browsers, the SPA routing service identifies the route information and download the chunk files associated to the route. This fallback setting looks as follows:

"navigationFallback": {     "rewrite": "index.html",     "exclude": ["/images/*.{png,jpg,gif}", "/css/*"]   },

 

On the fallback setting, we should note that we are doing a rewrite operation instead of redirect. This is efficient because a rewrite is handled on the server, so there is no client-side trip and another request as the redirect operation creates.  We should also notice that we do not want to rewrite missing resources to the index page. To avoid this, we exclude all the images and CSS files. The order on how these settings is configured on the file is also relevant. Usually, the settings that come later on the document take precedence and override the previous settings. To help on this, we can look at a complete staticwepapps.config.json.

Are There Client-Side Page Not Found Errors?

Yes, there are these errors as well. These errors are different from an HTTP 404 error. These client-side errors indicate that there is some call-to-action element on the app that has a path with no routing configuration. This is not a server error, so there should also be a fallback to handle that problem on the client routing configuration. This is often done by creating a wildcard route entry as the last route step, so when a route is not found, it can load the page not found component.

Conclusion

SPA application routing is done on the client-side of the application, but when the user does an operation that can cause the SPA to bootstrap again, a server-side request is made. If the hosting environment web server, CDN do not have routing configuration or a fallback to handle new routes added to the client side, the hosting environment returns a 404-error page that takes the user completely out of the application. Therefore, it is important to add routing to both the client and server and manage route issues on both ends. This should help us guards against 404 page not found errors.

Have you experienced similar problems with your apps? 

Send question or comment at Twitter @ozkary

Originally published by ozkary.com

Single Page Applications (SPA) handle the client-side routing or navigation of pages without the need to send a post back or request to the...

Read Article →

App Branding Strategy with GitHub Branches and Actions

Branding applications is a common design requirement. The concept is simple. We have an application with functional core components, but based on the partner or client, we need to change the theme or look of the design elements to match that of the client’s brand. Some of these design elements may include images, content, fonts, and theme changes. There are different strategies to support an app branding process, either in the build process or at runtime. In this article, we discuss how we can support a branding strategy using a code repository branching strategy and GitHub build actions.

Branching Strategy

A code repository enables us to store the source code for software solutions. Different branches are mostly used for feature development and production management purposes. In the case of branding applications, we want to be able to use branches for two purposes. The first is to be able to import the assets that are specific to the target brand. The second is to associate the branch to build actions which are used to build and deploy the branded application.

To help us visualize how this process works, let’s work on a typical branding use case. Think of an app for which there is a requirement to support two different brands, call them brand-a and brand-b. With this in mind, we should think about the design elements that need to be branded. For our simple case, those elements include the app title, logo, text, or messaging in JSON files, fonts, and the color theme or skin.

We now need to think of the build and deployment requirements for these two brands. We understand that each brand must be deployed to a different hosting resource with different URLs, let’s say those sites are hosted at brand-a.ozkary.com and brand-b.ozkary.com, These could be Static Web App or CDN hosting resources.

With the understanding that the application needs to be branded with different assets and must be built and deployed to different hosting sites, we can conclude that a solution will be to create different branches which can help us implement the design changes to the app and at the same time, enable us to deploy them correctly by associating a GitHub build action to each branch.

GitHub Actions

GitHub Actions makes it easy to automate Continuous Integration / Continuous Delivery (CI/CD) pipelines.  It is essentially a workflow that executes commands from a YML file to run actions like unit test, NPM build or any other commands that can be executed on the CLI to build the application.

A GitHub Action or workflow is triggered when there is a pull request (PR) on a branch. This is basically a code merge into the target branch. The workflow executes all the actions that are defined by the script. The typical build actions would be to pull the current code, move the files to a staging environment, run the build and unit test commands, and finally push the built assets into the target hosting location.

A GitHub Action is the great automation tool to meet the branding requirements because it enables us to customize the build with the corresponding brand assets prior to building the application. There is however some additional planning, so before we can work on the build, we need to define the implementation strategy to support a branding configuration.

Implementation Strategy

When coding a Web application with JavaScript frameworks, a common pattern is to import components and design elements into the container or pages of the application from their folder/path location. This works by either dynamically loading those files at runtime or loading them a design/build time.

The problem with loading dynamic content at runtime is that this requires that all the different brand assets be included in the build. This often leads to a big and slow build process as all those files need to be included. The design time approach is more effective as the build process would only include those specific features into the build, making the build process smaller and faster.

Using the design time approach does require a strategy. Even though, we could make specific file changes on the branch, to add the brand-a files as an example, and commit them, this is a manual process that is error prompt. We instead need an approach that is managed by the build process. For this process to work, we need to think of a folder structure within our project to better support it. Let’s review an approach.

After reviewing the image of the folder structure, we should notice that the component files import the resources from the same specific folder location, content. This off course is not enough to support branding, but by looking carefully, we should see that we have brand resources outside the src folder of the project in the brands' folder. There are also additional folders for each brand with the necessary assets.

This way this works is that only the files within the src and public folders are used for the build process. Files outside the src folder should not be included in the build, but they are still within source control.  The plan is to be able to copy the brand files into the src/content folder before the build action takes place. This is where we leverage a custom action on the GitHub workflow.

Custom Action

GitHub Actions enable us to run commands or actions during the build process. These actions are defined as a step within the build job, so a step to meet the branding requirements can be inserted into the job, which can handle copying the corresponding files to the content folders. Let’s look at a default workflow file that is associated to a branch, so we can see clearly how it works.

By default, the workflow has two steps, it first checks out or pull all the files from the code repo. It then executes the build commands that are defined in the package.json file. This is the steps that generates the build output, which is deployed to the hosting location. The logical step here is to insert a step or multiple steps to copy the files from all the brand subfolders. After making this suggested change, the workflow file should look as follows:

The new steps just copy files from the target brand folder into the src and public folders.  This should enable the build process to find those brand specific files and build the application with the new logo, fonts, and theme. The step to copy the fonts does some extra work. The reason is that the font files have different font family names, so we want to be able to find all the files and delete them first. We can then move forward and copy the new files.

It is important to notice that the SASS files, SCSS extension, are key players on this process. Those are the files that provide variable and font information to support the new color theme, styles, and fonts. When using SASS, the rest of the components only import those files and use the variables for their corresponding styles. This approach minimizes the number of files that need to be customized. The _font.scss file, for example, handles the font file names for the different brands, as those files are named differently.

 For cases where SASS is not used, it is OK to instead copy over the main CSS files that defines the color theme and style for the app, but the point should be to minimize the changes by centralizing the customization just by defining variables instead of changing all the style files as this can become hard to manage.

Conclusion

Branding applications is a common design requirement which can become difficult to manage without the right approach. By using a branching strategy and GitHub custom action, we can manage this requirement and prevent build problems by distributing the branded assets in different directory to keep the build process small. This approach also helps  eliminate the need to have developers make code commits just to make import reference changes.

Thanks for reading.

Gist Files

Default Action File

Branch-A Action File

Originally published by ozkary.com

Branding applications is a common design requirement. The concept is simple. We have an application with functional core components, but bas...

Read Article →

React Static Web Apps Manage ChunkLoadErrors on Dynamic Routes

The React JavaScript framework for Single Page Applications (SPA), which can be hosted on Azure Static Web Apps (SWA) or CDN hosting, supports the concept of Code Splitting by loading pages/routes dynamically instead of building one single package.  The benefit of Code Splitting is that it enables for faster load time on the user’s browser as opposed to loading the entire application on one single request. This feature however also introduces other concerns that we need to manage with code otherwise, the user can end up with a white page in front of them as the application is unable to render the requested content.

To leverage Code Splitting, we load the page routes by using React Lazy* Loading and Dynamic Import features. This way the page, or chunk, for the selected route is loaded only when it is requested. Because this is done a run-time, a new request is made to the server to download the chunk of code that is needed to render the page. Yes, this is a server-side trip to get the additional resources, and the application still works as an SPA.

Note:  Lazy loading is an application architecture that is used to load code in memory or web pages only when it is needed. This improves application performance and load time.

Because a server-side request must be made to download an additional chuck of code and render the route or page properly, there could be failures that are reflected as the following errors:

Uncaught ChunkLoadError: Loading chunk 2 failed.(timeout)

The failure could be due to two main reasons:

•         There is a network latency issue and the content failed to download
•          The client application may have been cached on the browser and App update has replaced those files with new hash codes

For the network problem, we can add some error handling and retry logic to allow the application to get the chunk again. We do need to be careful here and avoid locking the user on some retry logic because the second case, app update, can be happening, in which case the only way to solve the issue is by refreshing the entire app again.  Let’s look at the code below and talk about the root cause of this issue.

After looking at the code, we can see that we are lazy loading dynamic imports by using promises.  Those directives tell the compiler to create a chunk for that route, and when that route is dynamically requested by the user, the chunk is downloaded to the browser. The issue with this code is that there is no error handling, and promises can fail to download the chunk resulting on the ChunkLoadError.

To address this issue, we create a loader component that can manage both the error and attempts to download the requested chunk. At the same time, this component needs to be able to limit the number of retries, to avoid an infinite loop, and decide to load the entire app again. Let’s look at a simple implementation on how that could be done.

Loader Component

Using the Loader Component 

After looking at our solution, we can see that we are lazy loading the loader component which manages the promises, errors and retry activities. The component uses a default limit for the number of attempts that should try to download the next route. This is done by calling the same function recursively and decreasing the limit with every attempt until the limit is decrease to zero.  When the limit is reached, it does the next best thing, which is to reload the application.  If the chunk files for the current version of the application are still available, the retry logic should be able to solve the problem. Otherwise, a page reload takes place to download the application with the updated chunk information.

Code Gists

Route Loader Gist

Routes Gist

Conclusion

For this simple implementation, we decided to reload the application when a retry continues to fail. Depending on the use-case, the approach can be different. For example, a nice message can be displayed to the user explaining that a new update is available, and the application needs to be updated. This is the best user experience as feedback is provided to the user.

An important concern to consider when using Code Splitting is that a ChuckLoadError can take place for users with network issues or when a new update is pushed to production. Therefore, additional design and architecture considerations must be thought of before just adding the code splitting performance improvement to a React single page application.

Thanks for reading.

Originally published by ozkary.com

The React JavaScript framework for Single Page Applications (SPA), which can be hosted on Azure Static Web Apps (SWA) or CDN hosting, suppo...

Read Article →