As .NET evolves, so does the way we structure our applications. One notable change introduced in recent versions of .NET is the ability to merge `Startup.cs` and `Program.cs` into a single file. This approach streamlines the setup process, making it more cohesive and manageable. This article will discuss the rationale behind merging these files, walk through the process, and highlight potential advantages and pitfalls.

Merging Startup.cs and Program.cs in .NET 8: A Simplified Approach

As .NET evolves, so does the way we structure our applications. One notable change introduced in recent versions of .NET is the ability to merge `Startup.cs` and `Program.cs` into a single file. This approach streamlines the setup process, making it more cohesive and manageable. This article will discuss the rationale behind merging these files, walk through the process, and highlight potential advantages and pitfalls.

## Why Merge Startup.cs and Program.cs?
Okay, first let me try to find some advantages and also why it can be a bad idea.

### Advantages

1. **Simplified Structure**: By consolidating `Startup.cs` and `Program.cs`, you create a single entry point for application configuration. This can make the codebase more straightforward to navigate and understand. Updates to configuration or middleware can be made in one file rather than spread across multiple files, reducing the likelihood of inconsistencies and errors.

   
2. **Improved Testability**: With all configurations in one place, writing integration tests becomes simpler. Conditions and configurations are centralized, making it easier to mock dependencies and test different scenarios.

### Potential Pitfalls

1. **Complexity in Large Applications**: For very large applications, having all configurations in one file might become unwieldy. It's essential to balance simplicity with readability.
   
2. **Migration Challenges**: If you're transitioning an existing application, merging these files might introduce bugs if not done carefully. A rollback could be a nightmare (speaking from experience!).

## The Old Way: Separate Startup.cs and Program.cs

### Original Program.cs

```csharp
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Microsoft.Extensions.Logging.ApplicationInsights;
using System.Diagnostics;

public class Program
{
    public static void Main(string[] args)
    {
        try
        {
            Debug.WriteLine("Configure infrastructure...");
            BuildHost(args).Run();
        }
        catch (Exception ex)
        {
            Debug.WriteLine($"Infrastructure configuration failed: {ex}");
        }
    }

    public static IHost BuildHost(string[] args)
    {
        // Configuration and host building logic
    }
}
```

### Original Startup.cs

```csharp
using Microsoft.AspNetCore.Http.Features;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Options;
using Microsoft.FeatureManagement;
using System.Diagnostics;

public class Startup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment webHostEnvironment)
    {
        Configuration = configuration;
        WebHostEnvironment = webHostEnvironment;
    }

    public IConfiguration Configuration { get; }
    public IWebHostEnvironment WebHostEnvironment { get; }

    // Methods for configuring services and middleware
}
```

## The New Combined Mode

### Combined Program.cs

```csharp
using Microsoft.AspNetCore.Http.Features;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.ApplicationInsights;
using Microsoft.FeatureManagement;
using Newtonsoft.Json.Converters;
using System.Diagnostics;

var builder = WebApplication.CreateBuilder(args);

// Configuration setup
// Using builder.Configuration to setup configuration sources
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.UseFeatureFlags(o =>
    {
        o.Label = "InstanceName"; // Replace with your instance name
        o.CacheExpirationInterval = TimeSpan.FromMinutes(10);
    });
    options.ConfigureKeyVault(o =>
    {
        o.SetCredential(new DefaultAzureCredential()); // Replace with your Azure credential
        o.SetSecretRefreshInterval(TimeSpan.FromMinutes(30));
    });
    options.Connect("YourAppConfigurationEndpoint", new DefaultAzureCredential()) // Replace with your endpoint and credential
        .ConfigureRefresh(o =>
        {
            o.Register("Settings:Sentinel", refreshAll: true)
               .SetCacheExpiration(TimeSpan.FromMinutes(10));
        })
        .Select(KeyFilter.Any, LabelFilter.Null)
        .Select(KeyFilter.Any, labelFilter: "InstanceName"); // Replace with your instance name
});

if (builder.Environment.IsDevelopment())
{
    builder.Configuration.AddJsonFile("appsettings.json", optional: true);
    builder.Configuration.AddUserSecrets<Program>();
}

builder.Configuration.AddEnvironmentVariables();

// Logging setup
// Using builder.Logging to setup logging providers
builder.Logging.ClearProviders(); // Clear default providers
builder.Logging.AddConsole(); // Add console logging
builder.Logging.AddDebug(); // Add debug logging
builder.Logging.AddAzureWebAppDiagnostics(); // Add Azure diagnostics

if (!builder.Environment.IsDevelopment() && Environment.GetEnvironmentVariable("AUTOMATED_TESTING") is null)
{
    builder.Logging.AddApplicationInsights(config =>
    {
        config.ConnectionString = builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"];
        config.DisableTelemetry = false;
    }, options => options.IncludeScopes = false);
}

// Services setup
var services = builder.Services;
services.AddControllers().AddNewtonsoftJson(opt => opt.SerializerSettings.Converters.Add(new StringEnumConverter()));
services.AddDbContext<YourDbContext>(options => options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
services.AddFeatureManagement();
services.AddAzureAppConfiguration();
// Register other services as needed

// Middleware setup
var app = builder.Build();

app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

app.Run();

// Utility methods for retrieving services
private static T GetService<T>(IServiceCollection services)
{
    ServiceProvider serviceProvider = services.BuildServiceProvider();
    return serviceProvider.GetService<T>() ?? throw new Exception($"Could not find service {typeof(T)}");
}

private static T GetService<T>(IApplicationBuilder app)
{
    return app.ApplicationServices.GetService<T>() ?? throw new Exception($"Could not find service {typeof(T)}");
}

private static void DebugWrite(string message)
{
    Console.WriteLine(message);
    Debug.WriteLine(message);
}
```

### Key Points in the Combined File

- **Configuration**: Configuration sources are added using `builder.Configuration`. This includes Azure App Configuration, JSON files, user secrets, and environment variables.
- **Logging**: Logging is set up using `builder.Logging` with different providers for console, debug, and Application Insights. The `builder.Logging` API simplifies logging configuration by providing a centralized way to add and configure logging providers.
- **Services**: All service configurations, including custom services, middleware, and feature management, are consolidated. Using `builder.Services` makes it straightforward to register services with the dependency injection container.
- **Middleware**: Middleware components are configured in one place, improving readability and maintainability. The `app.UseRouting()`, `app.UseAuthentication()`, and `app.UseAuthorization()` methods set up the middleware pipeline.

### Our Experience and story
In our project, we have more than 100 active production instances, each with unique configuration and settings. 

We faced numerous conditions for integration tests, such as checking `Environment.GetEnvironmentVariable("AUTOMATED_TESTING")` or custom feature flag conditions based on license. 

All those conditions determine whether the application should use a different database or configure other testing-specific settings. And managing these conditions across multiple files was a pain in the a. 

Since merging `Startup.cs` and `Program.cs`, we have gained a much nicer overview and more control over our application. The centralized configuration has made it significantly easier to maintain and extend our application, particularly when writing and running integration tests and switching custom features.


### Conclusion

Merging `Startup.cs` and `Program.cs` can streamline your .NET applications, making them easier to test and maintain. However, be cautious during the transition to avoid introducing bugs. Start by merging the files as they are before making any improvements. This way, if something goes wrong, you'll have an easier time debugging (trust me, it happened to me...).

By following the steps and best practices outlined in this article, you can take advantage of the modern .NET hosting model and simplify your application's setup. 

I recently organized my first hackathon at my company, aimed at helping colleagues learn new things and create lasting memories 😊. Since it was my first attempt, I wanted to keep it internal. Here's how it went, what I learned, and some thoughts for anyone planning a similar event.

Organizing My First Hackathon: Lessons Learned



I recently organized my first hackathon at my company, aimed at helping colleagues learn new things and create lasting memories 😊. Since it was my first attempt, I wanted to keep it internal. Here's how it went, what I learned, and some thoughts for anyone planning a similar event.

## Setting the Scene

In my company, I organized a hackathon with the primary goal of learning and making memories. Since it was the first time, I kept it internal to ensure a comfortable environment for everyone. At the beginning, I had everyone write documentation to have a plan instead of diving straight into coding, which often leads to many rewrites. This approach also helped them appreciate the roles of project managers and product owners. I paired everyone into teams of two and had them try duo programming (navigator and driver) to get comfortable. Eventually, I let them work as they preferred, allowing creativity and collaboration to flourish.

## Scheduling Challenges

Choosing a date for more than ten people seemed impossible. After using Doodle to test different dates, we finally selected May 31. However, many people still couldn’t attend, and some canceled at the last minute. During the event, several participants had to leave early or didn’t stay until the end. I understand everyone has personal commitments, but I’m curious if there are ways to motivate attendees to stay for the entire event. Perhaps offering incentives or creating a more engaging agenda could help.

## The Importance of Support

Having a supportive CEO and HR made planning much easier. Before the event, I had many things to handle, like arranging food and coordinating schedules. Since the hackathon was on a Friday, I needed to request vacation time or coverage for project hours for everyone. Thankfully, our HR took care of all the food and drinks, allowing me to focus on other things. The CEO also gave everyone free paid time for Friday, which was fantastic. In other companies, employees usually need to take vacation days for such events, which wasn’t the case here. This support was crucial in making the event a success.

## Preparation Time

I underestimated the time needed to set up projects and get them running locally. For some teams, this took half a day, which felt like wasted time. Next time, I could prepare templates that are fully functional and set up cloud architecture so teams can focus on coding. However, this was also a great learning opportunity for some to create a new project from scratch. Despite this, I consider this a mistake on my part and a valuable lesson learned.

## Considering Allergens and Preferences

When ordering food or prizes, it’s important to know attendees’ allergens and preferences. For example, we had craft beer and special sweets as prizes, but some people might not drink alcohol or have diabetes. We prepared alternative gifts, like non-alcoholic beer, to show that we care about everyone’s needs. This might seem sentimental, but I think it’s important to show consideration and inclusivity.

## Team Composition

It’s usually better to create random teams, regardless of experience levels. Whether it’s two juniors, two seniors, or a mix, the results were always great. Colleagues who don’t normally work together got the chance to collaborate, which was a big plus. This approach fostered new connections and teamwork skills that might not have developed otherwise.

## Final Thoughts

This article might sound like PR, but I wrote it right after the event, fueled by adrenaline and caffeine, so it’s a bit "raw" 😅. If you’re planning a similar event, I’d highly recommend it. As a developer, this was a valuable experience. It’s a great way to learn, build memories, and foster a sense of community within the company. 

I’d love to hear others’ opinions, thoughts, and if they have similar plans! Let’s keep the conversation going! 🚀

## Additional Reflections and Tips

Reflecting on the event, I realized a few more points that might be helpful for others. First, it's crucial to have a clear agenda and communicate it effectively to all participants. This helps set expectations and keeps everyone on track. Second, having a dedicated space for the event, free from regular work distractions, can enhance focus and productivity. Lastly, gathering feedback from participants afterward can provide valuable insights for future improvements.

Organizing a hackathon is a lot of work, but seeing the enthusiasm and collaboration that it fosters is incredibly rewarding. If you’re considering organizing one, go for it! And don't hesitate to ask for help from your colleagues, especially those in HR and management, as their support can make a significant difference.

Looking forward to hearing about your experiences and tips for organizing successful hackathons! 😊

React 19's new hook simplifies handling asynchronous operations in React, especially when dealing with forms

Simplify Form Handling in React 19: Introducing `useActionState` Hook

React 19's new `useActionState` hook simplifies handling asynchronous operations in React, especially when dealing with forms. Let's delve into a practical example to see it in action.

Here we have a simple read-only form ready for submission:

```typescript
"use client";

export const FormAction = () => {
  return (
    <div>
      <form>
        <input type="text" name="name" value="Hello from actions" readOnly />
        <button type="submit">Submit</button>
      </form>
      <footer>
        <p>Awaiting action 🚀</p>
      </footer>
    </div>
  );
};
```

The `useActionState` hook takes a minimum of two arguments: (1) an asynchronous action, that in turn takes its own arguments of `previousState` and a generic payload, and (2) an initial state. This hook returns (a) the awaited state, (b) a dispatcher and (c) an `isPending` boolean.

```typescript
// canary.d.ts
export function useActionState<State, Payload>(
  action: (state: Awaited<State>, payload: Payload) => State | Promise<State>,
  initialState: Awaited<State>
): [
  state: Awaited<State>,
  dispatch: (payload: Payload) => void,
  isPending: boolean
];
```

So let's define our state's type definition along with our initial state value to begin shaping our component.

```typescript
"use client";

import { useActionState } from "react";

type State = { data: string; status: "SUCCESS" } | { status: "ERROR" | "INIT" };
const initState: State = { status: "INIT" };

export const FormAction = () => {
  const [action, submitAction, isPending] = useActionState(
    async (prevState: State, formData: FormData) =>
      runAction(prevState, String(formData.get("name"))),
    initState
  );

  return (
    <div>
      <form action={submitAction}>
        <input type="text" name="name" value="Hello from actions" readOnly />
        <button type="submit" disabled={isPending}>
          Submit
        </button>
      </form>
      <footer>
        {action.status === "INIT" && <p>Awaiting action 🚀</p>}
        {action.status === "SUCCESS" && <p>Success, all good ✅</p>}
        {action.status === "ERROR" && <p>Error, please resubmit action ❌</p>}
        <code>{JSON.stringify({ isPending })}</code>
        <code>{JSON.stringify(action)}</code>
      </footer>
    </div>
  );
};
```

- Notice how `submitAction`, a function generated by `useActionState`, is used directly in the form's `action` attribute. This moves away from the form pattern of using callbacks `onSubmit`.
- The submission button is disabled based on `isPending` which allows us to manage state effectively.
- As for the form's feedback mechanism, it responds dynamically to changes in action's `state`.

![Responsive UI](https://images.prismic.io/webscopeio/ZjisbkMTzAJOCkBs_use-action-state-preview.gif?auto=format,compress "Responsive UI")

The `runAction` function here is a mock, simulating an API call which randomly succeds or fails returning a new state, updating the form's status to either `SUCCESS` or `ERROR`. This could or could not be a [Server Action](https://www.webscope.io/blog/server-actions-resend).

```typescript
async function runAction(_prevState: State, data: string) {
  return new Promise<State>((r) => {
    setTimeout(
      () =>
        Math.random() < 0.5
          ? r({ data, status: "SUCCESS" })
          : r({ status: "ERROR" }),
      1500
    );
  });
}
```

> **Gotcha**: while this pattern allows you to keep your UI responsive, you need to design how to handle errors. This hook doesn't return an error member, so regardless if you are using a Server Action (where you can't throw errors) or not, you might have to follow the pattern showcased here integrating errors in the action's state.

Why not leverage `useActionState` in your next React project? What do you think? Does it make it easier or not to to manage state, side effects and boilerplate in form operations?

Here are some resources that we'd recommend you explore:

- [React 19 Beta Blog Announcement](https://react.dev/blog/2024/04/25/react-19)
- [`useActionState` API Reference](https://react.dev/reference/react/useActionState)
- [`useOptimistic` API Reference](https://react.dev/reference/react/useOptimistic)

Check out the code snippets and demo in [webscopeio/examples/tree/main/use-action-state](https://github.com/webscopeio/examples/tree/main/use-action-state)


React's Server Actions fundamentally streamline the implementation of email functionalities in web applications, making it a highly efficient and reliable solution

Using React's Server Actions and Resend for Emails

React's new source code directives provide instructions to bundlers compatible with React Server Components. The `'use server'` directive marks server-side functions that can be called from client-side code. React calls these functions **Server Actions**.

Today we will explore how to leverage Server Actions to send emails using [Next](https://nextjs.org/) (The React Framework for the Web) and [Resend](https://resend.com/) (The email API for developers).

## Why is this a good use case?

To send emails, your UI would typically have to trigger a POST request to an API endpoint. This would require setting up logic from both sides to send, manage states, process your request and provide an approriate response.

React's new `'use server'` directive makes this entire process easier if you need to setup email delivery fast. No API endpoints needed, you just _call a Server Action and you are done_.

## Getting started

In the context of a Next application, chances are that, you are or should be working with the following dependencies:

- [shadcn/ui](https://ui.shadcn.com/) Form Component which in turn includes dependencies such as [Zod](https://zod.dev/) for schema validation and static type inference and [React Hook Form](https://react-hook-form.com/) for the forms themselves
- [TanStack Query](https://tanstack.com/query/latest) for asynchronous state management
- [Resend](https://resend.com/) for sending the emails with [React Email](https://react.email/) or a component library such as [MailingUI](https://mailingui.com) for email templates.

## Is it safe to use Server Actions for this?

Behind the scenes, Server Actions use the POST method, and only this HTTP method is allowed to invoke them. This prevents most CSRF vulnerabilities in modern browsers. Server Actions in Next also compare request headers. If these don't match, the request will be aborted. In other words, Server Actions can only be invoked on the same host as the page that hosts it.

![Server Actions Network Request](https://images.prismic.io/webscopeio/ZgBRYMcYqOFdyDTe_01-server-actions-network-request.png "Server Actions Network Request")

A deeper read can be referenced in Sebastian Markbåge's [How to Think About Security in Next.js](https://nextjs.org/blog/security-nextjs-server-components-actions)

## Putting everything together

Let's build a simple UI that will allow users to claim a username.

### Schema Validation

Personally I like starting with my type definitions. Keeping everything incredibly simple, let's set up a schema:

```ts
import { z } from "zod";

export const usernameRequestForm = z.object({
  username: z.string().min(3),
});

export type UsernameRequestForm = z.infer<typeof usernameRequestForm>;
```

### Building our UI

Let's set up your Form component using your resolver and type definition from your schema. To show an example of optimistic updates we will also display a list of requests below the form.

```tsx
export const RequestForm: React.FC = () => {
  const form = useForm<UsernameRequestForm>({
    resolver: zodResolver(usernameRequestForm),
    defaultValues: {
      username: "",
    },
  });
  // ...
```

At form submission React Hook Form uses the schema defined to validate the form values. Using its `handleSubmit` method you are able to provide an `onValid` and/or `onInvalid` callbacks using the parsed values.

Typically you would define an `onSubmit` function and provide in the form's `onSubmit` attribute. However, you can invoke the `handleSubmit` method outside of the `onSubmit` attribute. Here are some examples:

#### Using `onSubmit` attribute

This is how [ui.shadcn.com/docs/components/form](https://ui.shadcn.com/docs/components/form) is used.

```tsx
<form onSubmit={form.handleSubmit(onSubmit)} />
```

#### Using `action` attribute

If you are using `react-hook-form`, this doesn't mean that you cannot make use of the `action` attribute.

```tsx
<form action={async () => await form.handleSubmit(onSubmit)()} />
```

#### Using a button's `onClick` handler

Or if you have different triggers in your form (i.e., a draft and save action), you can also use a button.

```tsx
<Button type="button" onClick={() => form.handleSubmit(onSubmit)()} />
```

We will be using a combination of these to showcase differents ways of using this structure with Server Actions.

### Server Actions

To call a Server Action in a Client Component, create a new file and add the `"use server"` directive at the top of it. All functions within the file will be marked as Server Actions that can be reused in both Client and Server Components.

To follow our example, we will send the user a confirmation via email after the request has been processed:

```ts
"use server";

import EmailTemplate from "@/emails/email-template";
import { Resend } from "resend";
import type { UsernameRequestForm } from "./types";

const resend = new Resend(process.env.RESEND_API_KEY);

function getCurrentUser() {
  return "sosa@webscope.io";
}

export async function claimUsername(form: UsernameRequestForm) {
  const userEmail = getCurrentUser();
  const { error } = await resend.emails.send({
    from: "From webscope.io <info@webscope.io>",
    to: [userEmail],
    subject: "Thank you for your message!",
    text: "We will reach out to you shortly",
    react: EmailTemplate(form),
  });

  if (error) {
    throw error;
  }

  return form;
}
```

Resend's SDK returns a `data` and `error` response in `CreateEmailResponse`. However, in this example we only make use of the error since the data only contains the email ID.

**Important note on error handling**: Just like in Server Components when using Server Actions, if an error is thrown during production, Next will strip any sensitive information and provide a generic error message and digest for log reference. This is a security precaution to avoid leaking any sensitive information included in the error to the client. You can read more about it in: [Handling Server Errors](https://nextjs.org/docs/app/building-your-application/routing/error-handling#handling-server-errors)

For the purposes of this article, we will continue working in development with unobscured error messages from Server Actions. If you do need to get specific error information from your errors, create and return an error object to the client.

### Handling States

Since Server Actions are just functions, it is up to us to handle states in our UI to provide an appropriate feedback to our user. These are roughly the states the UI needs:

- A `isPending` state while the Server Action is being processed.
- A `isError` state if the Server Action responds with an error.

![Displaying a Loading State](https://images.prismic.io/webscopeio/ZgBRYccYqOFdyDTf_02-loading-state.png "Displaying a Loading State")

Good to have are the following side-effects:

- A `onSuccess` callback once the Server Action is successful.
- A `onError` callback if the Server actions response with an error for next steps.


![Displaying a Error State](https://images.prismic.io/webscopeio/ZgBRYscYqOFdyDTg_03-error-state.png "Displaying a Error State")

Doesn't this sound like a perfect case for [TanStack Query](https://tanstack.com/query/latest)? Read their docs in [Mutations Guide](https://tanstack.com/query/latest/docs/framework/react/guides/mutations) for more information.

Following our example, this is how that would look like:

```tsx
const { isPending, isError, mutate } = useMutation({
  mutationFn: sendEmail,
  onSuccess: (_, variables) => {
    toast.success("Email sent!", {
      description: `Thanks for reaching out, ${variables.name}!`,
    });
  },
  onError: (error) => {
    toast.error("Something went wrong!", {
      description: error.message,
    });
  },
});
```

This gives us everything we need to process our request and handle our UI states.

We can also make use of an async mutation to provide immediate feedback using a promise `toast`:

```tsx
const { isPending, isError, mutateAsync } = useMutation({
  mutationFn: claimUsername,
});

function handleSubmit(values: UsernameRequestForm) {
  toast.promise(mutateAsync(values), {
    loading: `Submitting a claim for @${values.username}`,
    success: (data) => {
      form.reset();
      return `You have successfully submitted a claim for: @${data.username}`;
    },
    error: (error) => {
      return error instanceof Error ? error.message : "Unknown error";
    },
  });
}
```

### What if you are not using TanStack Query

This would be a mistake. However, you are able to make use of `useTransition` and `useOptimistic` hooks to trigger a Server Action and handle the different UI states. Here is what you need to keep an eye for:

* `useOptimistic` returns a tuple with a state and action. These actions can only be called within form's actions attributes or wrapped inside of a transition function.
* `useTransition` returns a tuple with a boolean and a **non-blocking** UI transition function. Even if being used inside a form's submit attribute, a transition provides a state for all the actions and not the handler (as `useFormStatus` would) which is not the same.

Let's make use of both of these hooks and call the Server Action directly without using TanStack Query Mutations.

```tsx
function handleSubmit(values: UsernameRequestForm) {
  startTransition(() => {
    addOptimisticRequest(values);
    toast.promise(claimUsername(values), {
      loading: `Submitting a claim for @${values.username}`,
      success: (data) => {
        form.reset();
        setRequests([
          ...requests,
          {
            ...data,
            status: "Requested",
          },
        ]);
        return `You have successfully submitted a claim for: @${data.username}`;
      },
      error: (error) => {
        setRequests([
          ...requests,
          {
            username: values.username,
            status: "Error",
          },
        ]);
        return error instanceof Error ? error.message : "Unknown error";
      },
    });
  });
}
```

Check out all the complete code snippets and the demo in [github.com/webscopeio/examples/tree/main/server-actions-resend](https://github.com/webscopeio/examples/tree/main/server-actions-resend)

## Will you give Server Actions a try?

React's Server Actions fundamentally streamline the implementation of email functionalities in web applications, making it a highly efficient and reliable solution. This guided example not only demonstrates the process from schema validation to state management but also emphasizes the ease of integration with essential web development tools, illustrating a holistic approach to modern web application development.

- **Simplified Process**: The introduction of Server Actions eradicates the necessity for back-and-forth logic between client and server to manage email sending, state processing, and response handling. By directly calling a Server Action, developers can swiftly set up email delivery mechanisms.

- **Reliable Security**: The security measures built into Server Actions, such as the exclusive use of the POST method and header verification to prevent CSRF vulnerabilities, offer a reliable security framework. This ensures that Server Actions are securely invoked only from the same host, minimizing potential security threats.

- **State Handling and Flexibility**: Handling UI states is crucial in providing user feedback. The use of TanStack Query, as recommended, facilitates this by offering a structured approach to mutations and state management.

So will you give Server Actions a try? Let us know why or why not and have fun! Thanks for reading!


Integrating a local Supabase setup with an email workflow is a game-changer for development efficiency and effectiveness

Creating an email workflow for local Supabase development

Local Supabase development is highly recommended for creating robust and efficient project workflows. With a local-first approach you can: (a) develop faster without any network latency or disruptions and even completely offline; (b) spin up unlimited Supabase instances free-of-cost; and (c) rely on code-based configurations and migrations making it easier to collaborate with team members on the same project. If you haven't tried it yet, you can read more in [Local development - How to use Supabase on your local development machine](https://supabase.com/docs/guides/cli/local-development).

Before getting started make sure that you:

- Install globally or locally (as a dev dependency) [Supabase CLI](https://supabase.com/docs/guides/cli/getting-started) to run the development stack locally on your machine.
- Install [Docker Desktop](https://docs.docker.com/desktop) to run the Docker containers required for the development stack.

This guide assumes you are working with Supabase CLI as a dev dependency. If you already have it installed globally, you can run all of the CLI commands directly, i.e. (use `supabase init` instead of `pnpm supabase init`).

This guide will help you build the following workflow:

1. Run a local Supabase instance
2. Run a local email development server using [React Email](https://react.email/docs/cli)
3. Set your [CLI configuration](https://supabase.com/docs/guides/cli/config) `supabase/config.toml` to include your email templates
4. Use [Inbucket](https://github.com/inbucket/inbucket) to capture emails sent from your local machine

## 1. Run a local Supabase instance

Go ahead and run the following commands:

```bash
# Create a cwd and initialize a project
mkdir supatest
cd supatest
pnpm init

# Install Supabase CLI as a dev dependency
pnpm add -D supabase

# Initialize and start
pnpm supabase init
pnpm supabase start
```

Once all of the Supabase services are running, you'll see the following output containing your local Supabase credentials:

```bash
        API URL: http://127.0.0.1:54321
     GraphQL URL: http://127.0.0.1:54321/graphql/v1
          DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
      Studio URL: http://127.0.0.1:54323
    Inbucket URL: http://127.0.0.1:54324
      JWT secret: super-secret-jwt-token-with-at-least-32-characters-long
        anon key: eyJh......
service_role key: eyJh......
```

From all of these we will be using:

- **Studio**: This container runs a web-based interface for managing your Supabase instance.
- **Inbucket**: This container runs an email testing service; it will accept messages for any email address and make them available via web interface.

### Additional information about Supabase CLI

What is good to know about the `supabase start` output:

- The environment variables are hard-coded and safe to include in your `.env.example` file
- You can use `supabase stop` at any time to stop all services (without resetting your local database). Use `supabase stop --no-backup` to stop all services and reset your local database

You can also add some of the Supabase CLI commands in your `package.json` for ease-of-use such as:

```json
"scripts": {
  "db:start": "supabase start",
  "db:stop": "supabase stop",
  "db:reset": "supabase db reset",
  "db:gen-types": "supabase gen types typescript --local > types/supabase.ts"
}
```

### Sending your first email

Go to Studio (using the Studio URL) and visit the Authentication page and click on "Add user" to send an invitation to any email. Once you have sent an invitation a new user will appear in a `Waiting for verification...` state.

![Supabase Studio Invite User](https://images.prismic.io/webscopeio/ZgBQ78cYqOFdyDTY_01-supabase-studio-invite-user.png "Supabase Studio Invite User")

Go to Inbucket (using the Inbucket URL) and your recently sent email should appear in "Monitor" or you will be able to find it under "Recent Mailboxes".

This is a fully functional email, but it isn't styled and it may not be the exact same email you want to send in production. Supabase Auth makes use of [Go Templates](https://pkg.go.dev/text/template) and you may be wanting to add more variables or add conditions based on the authentication method or user. You can read more about this in [Email Templates - Learn how to manage the email templates in Supabase](https://supabase.com/docs/guides/auth/auth-email-templates)

![Supabase Default Invite Email Template](https://images.prismic.io/webscopeio/ZgBQ8McYqOFdyDTZ_02-supabase-default-invite-email-template.png "Supabase Default Invite Email Template")

## 2. Run a local email development server using React Email

Enter React Email, a collection of high-quality, unstyled components for creating beautiful emails using React and TypeScript. React Email also has a CLI that is able to start a local development server for email development. Here's how to integrate it into your existing project.

```bash
# Add dependencies
pnpm add react @react-email/components

# Add dev dependencies
pnpm add -D react-email
```

With these dependencies we will be able to create, develop and test our emails using React Email's development server and use their CLI to generate HTML files for our Supabase project.

Again, here are some commands you can add in your `package.json` for ease-of-use:

```json
"scripts": {
  "email:dev": "email dev -p 4000",
  "email:export": "email export --outDir supabase/templates --pretty",
}
```

Before you run any of these commands make sure to create an `./emails` directory and create a `invite.tsx` file using this example [/examples/supabase-email-workflow/emails/invite.tsx](https://github.com/webscopeio/examples/blob/main/supabase-email-workflow/emails/invite.tsx)

All of the available variables for Suapbase Auth emails can be found in [Email Tempaltes Terminology](https://supabase.com/docs/guides/auth/auth-email-templates). Once you have set everything you need for email development you can continue with the following commands:

```bash
# Test your email development server running
pnpm email:dev

# Generate HTML for your templates running
pnpm email:export
```

![React Email Development Server](https://images.prismic.io/webscopeio/ZgBQ8ccYqOFdyDTa_03-react-email-development-server.png "React Email Development Server")

Once you are happy with your template and are ready to test your emails with Inbucket. You should make sure they are available in `supabase/templates` after running `pnpm email:export`.

## 3. Set your CLI configuration to include your email templates

You can customize all of the authentication emails in your CLI configuration using the `config.toml` file. This guide is only showcasing the invite email but you can read more about the other available email templates in [Customizing Email Templates](https://supabase.com/docs/guides/cli/customizing-email-templates).

```toml
[auth.email]
# Allow/disallow new user signups via email to your project.
enable_signup = true
# If enabled, a user will be required to confirm any email change on both the old, and new email
# addresses. If disabled, only the new email is required to confirm.
double_confirm_changes = true
# If enabled, users need to confirm their email address before signing in.
enable_confirmations = true

[auth.email.template.invite]
subject = "You have been invited"
content_path = "./supabase/templates/invite.html"

```

Remember, you will need to reset or restart your containers whenever the CLI configuration changes.

## 4. Use Inbucket to capture emails sent from your local machine

Now you can use Inbucket to test the email templates, use different email addresses, see how the variables are being loaded into the emails and test the different authentication flows. You should be able to see both the generated HTML and Plain Text from your email templates.

![Supabase New Invite Email Template](https://images.prismic.io/webscopeio/ZgBQ8scYqOFdyDTb_04-supabase-new-invite-email-template.png "Supabase New Invite Email Template")

These settings are only for local development. To update your hosted project, please copy the templates from `supabase/templates` into the [Email Templates](https://arc.net/l/quote/kjchbwqk) section of the Dashboard.

Keep in mind that for your production application you should update your SMTP configuration to use a service such as [Resend](https://resend.com). You can read more about this process in their guide [Supabase with SMTP](https://resend.com/docs/send-with-supabase-smtp)

## Main takeaways

To wrap up, integrating a local Supabase setup with an email workflow is a game-changer for development efficiency and effectiveness. Here's why this approach is a win-win:

- **Rapid Developmen**: Eliminating network delays with local Supabase speeds up development, while direct email testing slashes time to perfect email communications.
- **Cost-Effective**: Free unlimited Supabase instances keep your budget in check.
- **Team Synergy**: Code configurations ease collaboration and version control, and streamlined email development aligns your team on user communication strategies.
- **Quality Assurance**: With tools like React Email and Inbucket, you ensure your emails look great and work perfectly, enhancing the user experience.

Check out all the complete code snippets and the demo in [github.com/webscopeio/examples/tree/main/supabase-email-workflow](https://github.com/webscopeio/examples/tree/main/supabase-email-workflow)

Embrace this setup to boost your project's development workflow and deliver outstanding email communication. Give it a go, your project (and inbox) will thank you.


We tried to be clever and decided to ignore the first normal form (1NF) to "simplify" our database. And it went horribly. Read the story how.

Database Normalization: A Simple Tale of Ignoring 1NF

Let's dive into a quick chat about database normalization. If you've heard of it, awesome. If not, do not worry. This little story may shed light on why it's important.

### Database Normalization in a Nutshell

Picture this: you're trying to organize a big box of mixed-up Lego bricks. You'd probably sort them by color, size, or type, right? Database normalization is like that but for data! It's a way to sort and store your data neatly to avoid mix-ups and make sure everything is easy to find. For those who fancy a textbook definition, Wikipedia tells us:

> Database normalization is organizing a relational database to reduce data redundancy and improve data integrity.

In simpler terms: it's a set of rules (or "normal forms") that helps keep your data organized and your database running smoothly. However, the smoother your data, the trickier it might be to pull specific pieces when you need them.

### Bypassing 1NF: A Shortcut Gone Wrong
What this article will be a real story I have encountered in the past with one of the projects, where we tried to be clever and decided to ignore the first normal form (1NF) to "simplify" our database. 

Just to clarify, 1NF says:

> Every field should contain a single value, no sets of values or nested records allowed.

In other words: "Don't put tables inside of tables." But, of course, we did just that—tucked a table into another and found ourselves in a mess of complications and headaches.

## The story

Our journey commenced with the seemingly straightforward task of crafting a mechanism to store varied types of content – encompassing charts, custom HTML content, and checklists. The initial thought process nudged us toward the creation of a single table, structured as follows:

```sql
create table [dbo].[ContentSelection]
(
	[ContentPartSelectionID] int identity (1, 1) not null,
	[ConfigurationJSON] nvarchar(max) null,
	[ProfileTabID] int not null,
	[ContentType] int not null,
);
```

A singular majestic table, `ContentSelection`, was meant to graciously host various content types - charts, HTML blobs, or checklists, all neatly serialized and tucked into the `ConfigurationJSON` column. Oh, and a polite `ContentType` column to nudge us about what was packed inside each JSON, making deserialization ez thanks to .NET wizards like `System.Text.Json` and `Newtonsoft`.

### Problem 1: Navigating the Puzzle of Configuration Updates

Oh, the joys of updating configurations! Especially when dealing with JSON, it turned out to be a notable quest in our database management journey. Even seemingly simple tasks, like tweaking a chart's `Title` attribute, uncovered some pretty significant hurdles embedded in this method.

#### Simple Title Update in code: A Walk in the Park

In the world of coding, this task seemed like a walk in the park. The steps of deserialization, executing the update, and saving the JSON again could be done in a few simple steps:

```csharp
var data = JsonConvert.DeserializeObject<ChartConfiguration>(chart.ConfigurationJSON);
data.Title = "New Title";
chart.ConfigurationJSON = JsonConvert.SerializeObject(data);
// And the chart is saved!
```
This snippet of C# code allows developers to change the `Title` without diving deep into the entire JSON string. However, as the application goes, the code was all over the place, and this deserialization and serialization were done in many places. This is a code smell; we should have done it in one place. Sometimes, we just took the whole string and saved it as it is. I just trusted(hoped) that the client is sending the configuration in the correct state. Yeah, but that's a different story.

#### Simple but Not So Simple: The Database Update

Trying to update the configuration JSON directly within the database manually gave us a few options, each with its own set of complex puzzles:

1. **Whole JSON String Update:**
```sql
UPDATE [dbo].[ContentSelection] 
SET [ConfigurationJSON] = '{"Title": "New Title", "Type": "Chart", ...}'
WHERE [ContentPartSelectionID] = 1
```
Surprisingly, updating the entire JSON string, while seemingly straightforward, demands a meticulous understanding of the existing data structure to prevent any accidental data adventures (or misadventures).

2. **Making Friends with SQL Server’s JSON_MODIFY Function:**
```sql
UPDATE [dbo].[ContentSelection]
SET [ConfigurationJSON] = JSON_MODIFY([ConfigurationJSON], '$.Title', 'New Title')
WHERE [ContentPartSelectionID] = 1
```
The `JSON_MODIFY` function seemed like a neat and tidy update approach. Yet, it introduced a new set of complexities, particularly for those developers who might not be best buddies with SQL JSON manipulation functions.

#### HTML Property Challenges: An Additional Twist 

And then, things got particularly interesting when dealing with properties that encapsulate entire HTML strings. Direct updates weren't quite in the cards due to the necessity of escaping quotes to keep our JSON string in good shape. Thus, what seems like a straightforward update morphs into a careful dance of ensuring every character is correctly escaped and validated, amplifying the possibilities for error and inefficiency in database management.

---

### Problem 2: Leaping Over Initial Data Insertion Hurdles

Inaugurating a new production instance entailed inserting a wide variety of content—charts, checklists, and the like—into the `ContentSelection` table. What seemed like a straightforward task was, in reality, a hidden obstacle course.

#### The balance between Quantity vs. Quality 

Inserting many rows into the `ContentSelection` table meant wrestling with large strings of JSON configurations. Each piece of content, whether a chart or checklist, demanded a unique, error-free JSON string to guarantee smooth sailing in functionality and display.

Example JSON:
```json
{
  "Title": "Sample Chart",
  "Type": "Chart",
  "Configuration": {
    "Type": "Bar",
    "Data": {
      "Labels": ["January", "February", "March"],
      "Datasets": [{"Label": "Monthly Sales", "Data": [30, 25, 45]}]
    }
  }
}
```
Even the tiniest misstep, like a missing comma or mislabeled key, could introduce:

- **Data Integrity:** A chance of mischievous JSON disrupting data retrieval or manipulation.
- **User Experience:** The risk of misconfigurations causing a little chaos in content display or UI interactions.
- **Developer Efficiency:** The potential time-drain of debugging and correcting JSON strings.

#### The Sneaky "What-If" of Mistakes 

While seemingly trivial, an error in the JSON string can secretly trigger a chain reaction of operational disruptions, impacting developers and end-users alike. Though subtle, this issue beautifully underscores the crucial nature of precise data management and hints at the complex challenges that emerge when diverting from tried-and-true database normalization practices.

---

### Problem 3: Data Retrieval

While seemingly simple, extracting data from the `ContentSelection` table unveiled its complexity in deserializing JSON strings. This complexity, particularly when handling larger objects like comprehensive dashboards requiring multiple content elements, swells even more in cloud environments like Azure, where every computational second counts—both in performance and pennies.

### Problem 3.5 Search Operations: Not So Light on Serialized Columns 

Embarking on search operations within serialized columns is not just a stroll in the tech park. Here we are, navigating through JSON strings, demanding not just a splash, but a veritable ocean of additional computational prowess—especially when side-eyed with the columnar searches in our ever-so-organized normalized database setup. And as those JSON objects swell in size and complexity, our search operations mutate, becoming an increasingly obstinate beast, voraciously consuming resources and casually nudging our end-users’ response times into the slow lane.

And nvarchar(max), oh what a whimsical challenge for standard SQL server full search – a perfect storm of complexity all bundled up with a neat little bow. Thus, the serialized columns sashay through, daring us to keep pace without tripping over the nuances of adept database management. May the odds be ever in our favor!


### Problem 4: The Need for a Schema Update
We had multiple model classes within the source code with this comment.
> // Careful with renaming any of the properties here!!! - will break existing content parts

That's it. That explains it all. 

## The Solution: A Nod to 1NF

To alleviate the problems mentioned above, we pivoted towards adhering to the First Normal Form (1NF). It entailed restructuring our database, primarily by creating distinct tables for each content type, thus eliminating the need for JSON serialization within the database.

```sql
-- Original table, omitting the JSON column
create table [dbo].[ContentSelection]
(
    [ContentPartSelectionID] int identity (1, 1) not null,
    [ProfileTabID] int not null,
    [ContentType] int not null,
);

-- Additional tables
create table [dbo].[ChartConfiguration]
(
    [ContentPartSelectionID] int not null,
    [Title] nvarchar(max) null,
    [ChartType] int not null, -- e.g., 1 = Bar, 2 = Line, 3 = Pie
    [Values] nvarchar(max) not null,
    [XName]  nvarchar(100) not null,
    [YName]  nvarchar(100) not null
);

create table [dbo].[CustomContentConfiguration]
(
    [ChecklistConfigurationID] int identity (1, 1) not null,
    [ContentPartSelectionID] int not null,
    [Title] nvarchar(max) null,
    [Html] nvarchar(max) null,
);
... -- you get the idea
```

While effectively eliminating the need for extensive JSON operations within SQL, this solution required a meticulous migration process, ensuring existing customer data was transferred accurately and securely to the new structure.

### Navigating Through Data Migration

The transition demanded the crafting of migration scripts for each existing customer instance. 

```sql
insert into ChartConfiguration(ContentPartSelectionID, Title, Values, Type, XName, YName)
select
    ContentPartSelectionID,
    Json_Value(ConfigurationJSON, '$.title'),	   
    Json_Value(ConfigurationJSON, '$.values'),
    Json_Value(ConfigurationJSON, '$.ChartType'),
    Json_Value(ConfigurationJSON, '$.xName'),
    Json_Value(ConfigurationJSON, '$.yName')
from ContentSelection 
where ContentType = 1
```

Interestingly, this migration was multi-faceted and far from straightforward. For each content type, specific scripts were required. Moreover, each migration script must include checks to ensure data integrity, particularly validating JSON strings and managing instances where the `Json_Value` function misbehaved without apparent reason.

To safeguard against potential mishaps during the migration, the process was executed in two strategic phases: 
1. **Data Migration:** Transfer data without altering the original structure.
2. **Schema Update:** Only after verifying the migrated data did we modify the schema, like deleting the JSON column.

This dual-phase approach provided a safety net, ensuring that if complications arose at any point, a revert to the previous database state was always within reach. While resource-intensive, this strategy underscored the importance of meticulous planning and safeguarding data during migration, especially when restructuring to adhere to normalization principles like 1NF.

## Conclusion
This story concludes with a happy ending. We successfully migrated all our customers to the new structure and can now update the configuration of each content type without any problems. However, this story is not about the happy ending. It's about the issues we faced and how we solved them.

Take this story as a way to remind you to follow the best practices as much as possible. Even if you think you can do it better.

### One last note
Yes, I called them problems, not "challenges" or "opportunities". Because they were problems.
