Forem: Rishi Raj Jain

Using Partytown with Google Tag Manager in Astro: A Step-by-Step Guide

Rishi Raj Jain — Wed, 26 Nov 2025 23:19:42 +0000

In this guide, you will learn how to improve your Astro application's performance by integrating Partytown to offload Google Tag Manager to a Web Worker. You will go through the process of setting up a new Astro project, installing the Partytown integration, and configuring Google Tag Manager to run in a separate thread without blocking the main thread.

Prerequisites

You'll need the following:

Node.js 18 or later
A Google Tag Manager account with a container ID

What is Partytown?
Create a new Astro application
Integrate Partytown in your Astro project
- Install Partytown using Astro CLI
- Configure Partytown options
Add Google Tag Manager with Partytown
- Create a tracking component
- Use the tracking component in your layout
Test your Astro application locally
Understanding the Performance Benefits

What is Partytown?

Partytown is a library that relocates resource-intensive scripts into a web worker, and away from the main thread. This is particularly useful for third-party scripts like analytics and marketing tags that can slow down your website's performance. By offloading these scripts to a web worker, your main thread remains responsive, resulting in better Core Web Vitals scores and improved user experience.

Create a new Astro application

Let's get started by creating a new Astro project. Execute the following command:

npm create astro@latest my-app

npm create astro is the recommended way to scaffold an Astro project quickly.

When prompted, choose:

Empty when prompted on how to start the new project.
Yes when prompted if plan to write Typescript.
Strict when prompted how strict Typescript should be.
Yes when prompted to install dependencies.
Yes when prompted to initialize a git repository.

Once that's done, you can move into the project directory and start the app:

cd my-app
npm run dev

The app should be running on localhost:4321.

Now, let's move on to integrating Partytown in your Astro application.

Integrate Partytown in your Astro project

Install Partytown using Astro CLI

Astro provides a first-class integration for Partytown that makes setup incredibly simple. Execute the following command:

npx astro add partytown

When prompted, choose:

Yes when prompted whether to install the Partytown dependencies.
Yes when prompted whether to make changes to Astro configuration file.

The command above installs the @astrojs/partytown package and automatically configures your astro.config.mjs file. The integration handles copying the Partytown library files to the correct location in your build output, so you don't need to worry about manual setup.

Now, let's move on to configuring Partytown options.

Configure Partytown options

By default, the Partytown integration works out of the box, but you can customize its behavior for your specific needs. Open your astro.config.mjs file and you'll see the Partytown integration has been added:

import { defineConfig } from 'astro/config';
import partytown from '@astrojs/partytown';

export default defineConfig({
  integrations: [
    partytown({
      config: {
        forward: ['dataLayer.push'],
      },
    }),
  ],
});

The forward configuration is crucial for Google Tag Manager. It tells Partytown to forward calls to window.dataLayer.push() from the web worker to the main thread. This is necessary because Google Tag Manager uses the dataLayer array to send events and track user interactions.

Now, let's move on to adding Google Tag Manager with Partytown.

Add Google Tag Manager with Partytown

Create a tracking component

Create a new component to handle Google Tag Manager integration. Create a file src/components/GoogleTagManager.astro with the following code:

---
interface Props {
  containerId: string;
}

const { containerId } = Astro.props;
---

<script
  type="text/partytown"
  src={`https://www.googletagmanager.com/gtag/js?id=${containerId}`}
></script>
<script type="text/partytown" define:vars={{ containerId }}>
  window.dataLayer = window.dataLayer || [];
  window.gtag = function gtag() {
    dataLayer.push(arguments);
  };
  gtag('js', new Date());
  gtag('config', containerId);
</script>

The code above does the following:

Accepts a containerId prop for your Google Tag Manager container ID.
Loads the Google Tag Manager script with type="text/partytown" instead of the default type="module" or type="text/javascript".
Initializes the dataLayer array and gtag function that Google Tag Manager uses.
Configures Google Tag Manager with your container ID.

The key difference here is the type="text/partytown" attribute. This tells Partytown to intercept these scripts and execute them in a web worker instead of the main thread.

Now, let's move on to using this component in your layout.

Use the tracking component in your layout

Create a layout file src/layouts/Layout.astro to include the Google Tag Manager component:

---
import GoogleTagManager from '../components/GoogleTagManager.astro';

interface Props {
  title: string;
}

const { title } = Astro.props;
---

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <meta name="generator" content={Astro.generator} />
    <title>{title}</title>
    <GoogleTagManager containerId="GTM-XXXXXXX" />
  </head>
  <body>
    <slot />
  </body>
</html>

Make sure to replace GTM-XXXXXXX with your actual Google Tag Manager container ID. You can find this ID in your Google Tag Manager account under Admin > Container Settings.

Now update your src/pages/index.astro file to use this layout:

---
import Layout from "../layouts/Layout.astro";
---

<Layout title="Welcome to Astro with Partytown">
  <main>
    <h1>Welcome to Astro</h1>
    <p>Your Google Tag Manager is now running in a web worker!</p>
    <!-- <button track-me> Track Custom Event </button> -->
  </main>
</Layout>

Test your Astro application locally

To test the application, start the development server using the command below:

npm run dev

Open your browser's developer tools and navigate to the Network tab. You should see the Google Tag Manager script being loaded. To verify that Partytown is working correctly:

Open the Application tab (Chrome) or Storage tab (Firefox) in developer tools.
Look for Web Workers in the left sidebar.
You should see a Partytown web worker running, indicating that your scripts are successfully offloaded.

You can also check the Console tab for any Partytown-related messages or errors.

Understanding the Performance Benefits

By moving Google Tag Manager to a web worker with Partytown, you gain several performance benefits:

Improved Main Thread Performance: Analytics and marketing scripts no longer compete for resources on the main thread, keeping your UI responsive.
Better Core Web Vitals: Particularly Total Blocking Time (TBT) and First Input Delay (FID) scores improve significantly.
Faster Page Load: The browser can prioritize rendering and user interactions over third-party scripts.

For Google Analytics 4 (GA4), which is the current version of Google Analytics, the responses come with the correct CORS headers. This means you won't need to set up proxying for requests to www.google-analytics.com, making the integration even simpler.

If you need to track custom events, you can use the dataLayer.push() method anywhere in your application:

<button track-me>Track Custom Event</button>

<script type="text/partytown">
  document.querySelectorAll("button[track-me]").forEach((button) => {
    button.addEventListener("click", () => {
      dataLayer.push({
        event: "button_click",
      });
    });
  });
</script>

Thanks to the forward: ['dataLayer.push'] configuration in Partytown, these events will be properly forwarded from the web worker to the main thread and sent to Google Tag Manager.

References

Conclusion

In this guide, you learned how to integrate Partytown with Google Tag Manager in an Astro application to improve performance by offloading third-party scripts to a web worker. You've also gained experience with using Astro's first-class integrations and understanding how web workers can help optimize your application's Core Web Vitals.

If you have any questions or comments, feel free to reach out to me on Twitter.

Comparing Text Search Strategies pg_search vs. tsvector vs. External Engines

Rishi Raj Jain — Thu, 08 May 2025 17:01:53 +0000

Choosing the Right Search Approach for Your Application with PostgreSQL and Neon Postgres.

When implementing search in your application, you need to choose the right text search approach. This guide compares PostgreSQL's built-in tsvector, the pg_search extension, and external search engines to help you select the best option for your needs.

Built-in PostgreSQL `tsvector` for Text Search

PostgreSQL includes native full-text search capabilities using the tsvector data type and tsquery search expressions. The tsvector data type is a specialized data structure that PostgreSQL uses to represent documents in a form optimized for search.

This built-in functionality works for basic search needs without requiring any additional extensions. It's perfect for smaller applications or when you don't require advanced search features.

Example of Using `tsvector`

To use tsvector, you need to create a table with a column to store the search vector. You can then convert text into the tsvector format and create an index for efficient searching. This allows your queries to run faster, even as your dataset grows.

CREATE TABLE articles (
    id SERIAL PRIMARY KEY,
    title TEXT,
    content TEXT,
    search_vector tsvector
);

-- Update the search vector
UPDATE articles
SET search_vector = to_tsvector('english', title || ' ' || content);

-- Create an index on the search vector
CREATE INDEX idx_search_vector ON articles USING GIN (search_vector);

-- Query using tsquery
SELECT id, title
FROM articles
WHERE search_vector @@ to_tsquery('english', 'database & performance');

This example shows how to:

Create a table with a column to store search vectors
Convert text to the tsvector format using the to_tsvector function
Create a GIN index to speed up searches
Search for articles containing both "database" and "performance"

While tsvector meets basic search needs, it has limitations with relevance ranking, handling typos, and complex search patterns. It’s suitable for small to medium-sized datasets where advanced features aren’t necessary.

Pros of `tsvector`

Simplicity: No need for any extensions, just native PostgreSQL functionality.
Integrated with Postgres: Works seamlessly within the same database, avoiding the need for additional services.
Low overhead: Since tsvector is part of Postgres, it doesn’t require a separate system to maintain.

Cons of `tsvector`

Limited relevance ranking: It doesn't automatically rank search results based on relevance.
No typo tolerance: Exact matches are required, so if a user misspells a search term, it won’t return relevant results.
Complex queries: Handling more complex queries like fuzzy matching or phrase proximity is not possible out-of-the-box.

Extending `tsvector` with `pg_search`

The pg_search extension builds on PostgreSQL's search capabilities by adding better relevance ranking with the BM25 algorithm, fuzzy matching for handling typos, and more flexible search options.

This extension is particularly useful for applications that require more sophisticated search features without needing a separate search engine.

With pg_search, you get features such as:

Relevance Ranking: The BM25 algorithm provides an automatic ranking of search results based on how relevant they are to the query.
Fuzzy Matching: It allows for typo tolerance, meaning searches will return relevant results even when a user makes small errors.
Phrase Search: You can search for exact phrases or words that are close together, which can be especially useful in content-heavy applications.
Flexible Queries: pg_search supports more complex search expressions like partial word matches, stemming, and stop-word filtering.

Enabling `pg_search` on Neon

pg_search is currently only available on Neon projects created in an AWS region.

Adding pg_search to your Neon database is simple - just run this single SQL command:

CREATE EXTENSION IF NOT EXISTS pg_search;

That's all it takes to enable the extension. You can then use the pg_search features in your queries. The setup is straightforward, and you don’t need any additional infrastructure to get started.

Example of Using `pg_search`

After enabling the extension, you can create search indexes and run more sophisticated queries:

-- Create a BM25 index on multiple columns
CREATE INDEX article_search_idx ON articles
USING bm25 (id, title, content)
WITH (key_field='id');

-- Simple keyword search
SELECT title
FROM articles
WHERE title @@@ 'database';

-- Handling typos with fuzzy matching
SELECT title
FROM articles
WHERE id @@@ paradedb.match('title', 'database', distance => 1);

-- Sorting by relevance score
SELECT title, paradedb.score(id) AS relevance
FROM articles
WHERE content @@@ 'performance'
ORDER BY paradedb.score(id) DESC;

This code shows how to:

Create a BM25 index that covers multiple columns
Perform a basic keyword search using the @@@ operator
Find results even when the search term has typos
Sort results by relevance so the most relevant results appear first

Why Use `pg_search` on Neon?

Using pg_search on Neon gives you:

Better search capabilities: With ranking, typo tolerance, and complex query options, pg_search provides much more functionality than tsvector.
A fully managed PostgreSQL experience: You don’t need to set up or maintain a separate search service. Neon handles everything for you, from scaling to backups.
Data consistency: Since the search index is part of your PostgreSQL database, there’s no need to worry about synchronizing data between separate systems.
Simple architecture: With pg_search running on Neon, you avoid the complexity of managing an external search engine while still getting advanced search features.

pg_search is a great choice for applications that need more advanced search features but want to avoid the complexity of managing a separate search engine.

External Search Engines (e.g., Elasticsearch)

External search engines like Elasticsearch provide specialized search features for complex use cases and very large datasets. These engines are designed to scale out across many servers and handle high-performance, low-latency search queries.

While these engines offer powerful capabilities, they come with trade-offs:

You need to set up and maintain additional infrastructure: External search engines require managing separate servers or cloud services, which can increase operational overhead.
You must keep your database and search index synchronized: Ensuring that your external search engine stays in sync with your PostgreSQL database can introduce complexity, especially as your data changes.
Increased complexity: Managing another system means additional configuration, monitoring, and troubleshooting.
Higher operational costs: Running an external search engine comes with extra costs, both in terms of infrastructure and developer time.

External search engines like Elasticsearch provide powerful features such as:

Distributed search: Handles large-scale search queries across many machines.
Complex querying: Offers advanced querying capabilities such as aggregations, nested fields, and more.
Real-time indexing: Updates search results in real time as new data is indexed.

Use Cases for External Search Engines

You might choose an external search engine when:

You have extremely large datasets (billions of records) that require distributed search across multiple servers.
Your search needs include specialized features not available in PostgreSQL, such as advanced analytics, geographic search, or machine learning integration.
You have the resources to manage additional infrastructure and complexity.

Comparison Summary

Feature	`tsvector`	`pg_search` on Neon	External Engines
Setup	Built into Postgres	Easy setup on Neon	Separate system to install, configure and maintain
Relevance Ranking	Basic	BM25 ranking	Advanced ranking options
Typo Tolerance	No	Yes	Yes
Query Flexibility	Limited	Good	Extensive
Scaling	Limited by Postgres	Managed by Neon	Requires manual scaling
Cost	Included with Postgres	Included with Neon	Additional infrastructure costs
Maintenance	Minimal	Handled by Neon	Requires ongoing maintenance

Which Option Should You Choose?

With all these options available, how do you choose the right one for your application? Here are some guidelines:

Use built-in `tsvector` when:

You have simple search requirements
Your dataset is small to medium-sized
You want to use only built-in PostgreSQL features

Use `pg_search` on Neon when:

You need better search relevance and typo tolerance
You want to avoid setting up separate systems
You prefer a managed database experience
Your search needs are important but don't require specialized features

Consider external search engines when:

You have extremely large datasets (billions of records)
Your search needs include specialized features not available in PostgreSQL
You have the resources to manage additional infrastructure

For most web applications, content sites, and e-commerce platforms, pg_search on Neon provides a great balance between search features and simplicity. It extends PostgreSQL's capabilities without requiring you to manage separate systems or synchronize data.

Conclusion

When choosing a search strategy, start with the simplest option that meets your needs. For many applications, pg_search on Neon offers a great middle ground - better search features than native PostgreSQL without the complexity of a separate search system.

Selecting the right search approach allows you to provide good search functionality to your users while keeping your application architecture as simple as possible.

Building a RESTful API with ASP.NET Core, Swagger, and Neon

Rishi Raj Jain — Thu, 23 Jan 2025 19:19:14 +0000

In this guide, we'll walk through the process of developing a RESTful API using ASP.NET Core, connecting it to a Neon Postgres database. We will cover CRUD operations using Entity Framework Core (EF Core), generate interactive API documentation with Swagger, and explore best practices for testing your API endpoints. As a bonus, we'll also implement JWT authentication to secure your endpoints.

Prerequisites

Before we start, make sure you have the following:

.NET SDK 8.0
Neon account for setting up your Postgres database
Postman for API testing
Basic knowledge of C# and ASP.NET Core
Familiarity with Entity Framework Core

Setting Up Your ASP.NET Core Project

First, create a new ASP.NET Core Web API project:

dotnet new webapi -n NeonApi
cd NeonApi

Install the required NuGet packages using the dotnet add package command:

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
dotnet add package Swashbuckle.AspNetCore
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
dotnet add package Microsoft.EntityFrameworkCore.Design

The above packages include:

Microsoft.EntityFrameworkCore - Entity Framework Core for database operations
Npgsql.EntityFrameworkCore.PostgreSQL - PostgreSQL provider for EF Core
Swashbuckle.AspNetCore - Swagger for API documentation
Microsoft.AspNetCore.Authentication.JwtBearer - JWT authentication for securing endpoints
Microsoft.EntityFrameworkCore.Design - EF Core design tools for migrations

Configuring the Neon Database

Head over to your Neon Dashboard and create a new project.

Once done, grab your database connection string and add it to your appsettings.json:

"ConnectionStrings": {
  "NeonDb": "Host=<your-host>;Database=<your-database>;Username=<your-username>;Password=<your-password>;Port=5432"
}

While you're in appsettings.json, add a section for JWT authentication after the connection string:

"Jwt": {
"SecretKey": "your-very-secure-secret-key"
}

We will cover JWT authentication in more detail later in this guide, but for now, let's focus on setting up the API.

Next, update your Program.cs file to include the database context, Swagger, and JWT authentication:

using NeonApi.Data;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.EntityFrameworkCore;
using Microsoft.IdentityModel.Tokens;
using System.Text;

var builder = WebApplication.CreateBuilder(args);
var configuration = builder.Configuration;

// Add the Neon database context using Npgsql provider
builder.Services.AddDbContext<NeonDbContext>(options =>
    options.UseNpgsql(configuration.GetConnectionString("NeonDb")));

// Register controllers for handling incoming HTTP requests
builder.Services.AddControllers();

// Enable API endpoint exploration and Swagger documentation
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Set up JWT authentication to secure API endpoints
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            // Validate that the token is signed with the specified key
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(configuration["Jwt:SecretKey"])),

            // Disable issuer and audience validation for testing purposes
            ValidateIssuer = false,
            ValidateAudience = false
        };
    });

var app = builder.Build();

// Configure the middleware pipeline
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

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

app.Run();

In the above, we configure the necessary services directly within Program.cs to connect our ASP.NET Core API to Neon and secure it with JWT authentication:

We use AddDbContext to set up NeonDbContext with the Npgsql provider, connecting to the Neon database using the connection string defined in appsettings.json. Make sure to update "NeonDb" with your actual connection string key if it's named differently.
We register controllers with AddControllers(), which allows the application to handle incoming API requests and map them to their respective endpoints.
By adding EndpointsApiExplorer and SwaggerGen, we enable automatic generation of API documentation. This provides a user-friendly interface to interact with your API endpoints, accessible at /swagger.
For the JWT authentication setup, we are implementing the following:
- Here, we set up JWT authentication to protect your API routes. We use AddJwtBearer to validate tokens sent by clients.
- The TokenValidationParameters section allows us to make sure that the token is signed with the specified key. Replace "your-secret-key" in appsettings.json with a secure key unique to your application.
- For simplicity, ValidateIssuer and ValidateAudience are set to false, which means the API won't check who issued the token or its intended audience. This is useful for local development but should be tightened for production environments.

To avoid hardcoding sensitive information like the secret key, consider using environment variables or a configuration management system to securely store secrets.

Creating the Entity Framework Core Models

Data models define the structure of your database tables and the relationships between them. Here, we'll create a simple Product model to represent products in our Neon database.

In the Models folder, create a Product.cs file:

namespace NeonApi.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public decimal Price { get; set; }
        public string Description { get; set; }
    }
}

Here, we define a simple Product model with four properties:

Id: This is the primary key, which will auto-increment.
Name: Stores the product's name.
Price: Holds the product's price as a decimal value.
Description: Provides additional details about the product.

Each property corresponds to a column in the database table that Entity Framework will generate for us.

Creating the Database Context

Next, we need to create a database context class, which serves as a bridge between our C# code and the Neon database.

Create a new folder named Data and add a NeonDbContext.cs file:

namespace NeonApi.Data
{
    public class NeonDbContext : DbContext
    {
        public NeonDbContext(DbContextOptions<NeonDbContext> options) : base(options) { }

        // This DbSet represents the Products table in the Neon database
        public DbSet<Product> Products { get; set; }
    }
}

The above code snippet does the following:

The NeonDbContext class inherits from DbContext, which is part of Entity Framework Core.
We pass DbContextOptions to the constructor to configure the connection to our Neon database.
The DbSet<Product> property represents the Products table. This allows us to perform CRUD operations on the Product model directly through this context.

Running Migrations to Create the Database Schema

Now that we have defined our model and context, let's generate the database schema using migrations. Open your terminal and run the following commands:

dotnet ef migrations add InitialCreate

The above command generates a migration file based on the changes made to the database schema. The migration file contains instructions to create the Products table.

Next, apply the migration to your Neon database:

dotnet ef database update

The dotnet ef database update command applies the migration to your Neon database, creating the Products table and any other necessary schema changes.

Note: Make sure your database connection string in appsettings.json is correctly configured before running the migrations. That way the changes are applied to your Neon database instance.

At this point, your database is set up and ready to store product data!

Building the API Endpoints

With the database schema in place, let's create the API endpoints to perform CRUD operations on the Products table.

In the Controllers folder, create a ProductsController.cs file with the following content:

using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using NeonApi.Data;
using NeonApi.Models;

[Route("api/[controller]")]
[ApiController]
public class ProductsController : ControllerBase
{
    private readonly NeonDbContext _context;

    public ProductsController(NeonDbContext context)
    {
        _context = context;
    }

    [HttpGet]
    public async Task<ActionResult<IEnumerable<Product>>> GetProducts()
    {
        // Retrieve all products from the database
        return await _context.Products.ToListAsync();
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<Product>> GetProduct(int id)
    {
        // Retrieve a single product by ID
        var product = await _context.Products.FindAsync(id);
        if (product == null) return NotFound(); // Return 404 if not found
        return product;
    }

    [HttpPost]
    public async Task<ActionResult<Product>> CreateProduct(Product product)
    {
        // Add a new product to the database
        _context.Products.Add(product);
        await _context.SaveChangesAsync();

        // Return 201 Created status with the newly created product
        return CreatedAtAction(nameof(GetProduct), new { id = product.Id }, product);
    }

    [HttpPut("{id}")]
    public async Task<IActionResult> UpdateProduct(int id, Product product)
    {
        // Ensure the ID in the URL matches the ID of the provided product
        if (id != product.Id) return BadRequest();

        // Mark the product as modified
        _context.Entry(product).State = EntityState.Modified;
        await _context.SaveChangesAsync();

        // Return 204 No Content status after a successful update
        return NoContent();
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteProduct(int id)
    {
        // Find the product by ID
        var product = await _context.Products.FindAsync(id);
        if (product == null) return NotFound(); // Return 404 if not found

        // Remove the product from the database
        _context.Products.Remove(product);
        await _context.SaveChangesAsync();

        // Return 204 No Content status after successful deletion
        return NoContent();
    }
}

In the code above, we define a ProductsController to handle all CRUD operations for our Product model. Here's a breakdown of how each endpoint works:

The GetProducts method handles GET /api/products requests, fetching all products stored in the Neon database.
The GetProduct method handles GET /api/products/{id} requests to retrieve a single product by its unique ID. If no product with the given ID is found, it responds with a 404 Not Found. This ensures the client is notified when attempting to access a non-existent product.
The CreateProduct method handles POST /api/products requests to add a new product. The response uses CreatedAtAction to include a link to the newly created resource, following REST best practices.
The UpdateProduct method handles PUT /api/products/{id} requests to modify an existing product. Once the update is successful, it responds with a 204 No Content, indicating the operation was successful without returning any additional data.
The DeleteProduct method handles DELETE /api/products/{id} requests to remove a product by its ID. If the product doesn't exist, it returns a 404 Not Found response.

Each endpoint is fully asynchronous and interacts with the Neon database through the NeonDbContext context.

Setting Up Swagger for API Documentation

To document our API and provide an interactive interface for testing, we'll integrate Swagger into our ASP.NET Core project.

Swagger automatically generates OpenAPI documentation, making it easy to explore your API and test its endpoints directly from your browser.

Enabling Swagger in `Program.cs`

To set up Swagger, add the following code in the Configure method of your Program.cs file:

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    // Configure Swagger UI at the root URL
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Neon API V1");
    c.RoutePrefix = string.Empty;
});

The UseSwagger middleware generates the OpenAPI documentation for your API, while UseSwaggerUI sets up the Swagger interface for interacting with your endpoints.

Running Your Application

Now that Swagger is set up, start your application using:

dotnet run

Once the application is running, you will see the port where your API is hosted (usually https://localhost:5229), eg.:

Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5229

Visit https://localhost:5229/swagger in your browser to access the Swagger UI.

The Swagger UI will appear, displaying all your API endpoints with detailed documentation. You can test the endpoints by sending requests directly from the UI and viewing the responses, making it easy to verify that everything works as expected.

Testing Your API with Postman

Now that your API is running, you can use Postman or any other API testing tool to interact with your endpoints. You can even use the Swagger UI to test the endpoints, but Postman provides a more robust environment for testing complex scenarios.

In this section, we'll walk through testing the CRUD operations using Postman but feel free to use any tool you're comfortable with like Insomnia or cURL.

Download and launch Postman. Create a new request to interact with your API.

Open Postman and create the following requests:

GET: /api/products

Description: Fetches all products.
Set to GET, enter https://localhost:5001/api/products, and click Send.
You should receive a 200 OK response with a list of products.

POST: /api/products

Description: Creates a new product.
Set to POST, enter https://localhost:5001/api/products, and go to Body → raw → JSON.

Add:

 {
   "name": "New Product",
   "price": 19.99,
   "description": "Sample product"
 }

Click Send. Expect a 201 Created response.

PUT: /api/products/{id}

Description: Updates a product.
Set to PUT, enter https://localhost:5001/api/products/1.

Add:

 {
   "id": 1,
   "name": "Updated Product",
   "price": 29.99,
   "description": "Updated description"
 }

Click Send. You should receive a 204 No Content.

DELETE: /api/products/{id}
- Description: Deletes a product.
- Set to DELETE, enter https://localhost:5001/api/products/1, and click Send.
- Expect a 204 No Content.

After testing, check that all changes are reflected in your Neon database. Use both Postman and Swagger UI to confirm the endpoints are functioning correctly.

Securing Your API with JWT Authentication (Bonus)

To protect your API endpoints, we’ll use JWT (JSON Web Token) authentication. By adding the [Authorize] attribute to specific controller actions, you can ensure that only authenticated users have access. Here’s how to secure the GetProducts endpoint:

[Authorize]
[HttpGet]
public async Task<ActionResult<IEnumerable<Product>>> GetProducts()
{
    return await _context.Products.ToListAsync();
}

Now, any requests to GetProducts will require a valid JWT token, if you try to access the endpoint without a token, you will receive a 401 Unauthorized response.

Generating and Using JWT Tokens

When a user successfully logs in, the server generates a JWT token containing the user's authentication details. This token typically includes claims such as the user's ID, email, and a unique identifier. The token is then signed with a secret key to ensure its integrity and prevent tampering. For example:

public string GenerateJwtToken(User user)
{
    var claims = new[]
    {
        new Claim(JwtRegisteredClaimNames.Sub, user.Id.ToString()),
        new Claim(JwtRegisteredClaimNames.Email, user.Email),
        new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
    };

    var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(configuration["Jwt:SecretKey"]));
    var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

    var token = new JwtSecurityToken(
        issuer: null,
        audience: null,
        claims: claims,
        expires: DateTime.UtcNow.AddHours(1),
        signingCredentials: creds);

    return new JwtSecurityTokenHandler().WriteToken(token);
}

The token looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZW1haWwiOiJhZG1pbkBleGFtcGxlLmNvbSIsImp0aSI6IjMzYjQwMzIwLWUwZjItNDIwZi1iZjIwLWUwZjIwZmJmMjAwMCIsImV4cCI6MTY0MzUwNzQwMH0.7

If you were to go to jwt.io, you could paste the token and see its decoded contents.

Once the token is generated, the client stores it in local storage or session storage and includes it in the Authorization header for all subsequent requests to secured endpoints. For instance:

Authorization: Bearer <your-jwt-token>

With this header in place, the server can authenticate the user without requiring them to log in again for each request.

Conclusion

In this guide, we covered the process of building a RESTful API with ASP.NET Core, connecting it to a Neon Postgres database, and securing it with JWT authentication. We explored CRUD operations using Entity Framework Core, generated interactive API documentation with Swagger, and tested our endpoints using Postman.

As a next step, consider expanding your API with additional features, such as pagination, filtering, or sorting. You can also explore adding testing frameworks like xUnit or NUnit to write unit tests for your API endpoints.

For more information, check out:

Creating a Multi-Tenant Application with Laravel and Neon

Rishi Raj Jain — Fri, 10 Jan 2025 19:27:38 +0000

Multi-tenancy is a software architecture where a single instance of an application serves multiple tenants or clients.

Each tenant's data is isolated and remains invisible to other tenants. This approach is commonly used in Software as a Service (SaaS) applications. In this tutorial, we'll build the foundation for a multi-tenant SaaS application using Laravel and Neon.

By the end of this tutorial, you'll have a fully functional multi-tenant SaaS application where tenants can manage their own books, users, and settings, all while maintaining data isolation between tenants.

Prerequisites

Before we start, make sure you have the following:

PHP 8.1 or higher installed on your system
Composer for managing PHP dependencies
Node.js and npm for managing front-end assets
A Neon account for database hosting
Basic knowledge of Laravel and Livewire

Setting up the Project

Let's start by creating a new Laravel project and setting up the necessary components.

Creating a New Laravel Project

Open your terminal and run the following command to create a new Laravel project:

composer create-project laravel/laravel laravel-multi-tenant-saas
cd laravel-multi-tenant-saas

Installing Required Packages

For our multi-tenant SaaS application, we'll use the following package:

stancl/tenancy: A flexible multi-tenancy package for Laravel
Laravel Breeze: A minimal authentication starter kit for Laravel

Start by installing the stancl/tenancy package:

composer require stancl/tenancy

After installing the package, let's set up the tenancy:

php artisan tenancy:install

return [
    // ...
    App\Providers\TenancyServiceProvider::class,
],

Let's install Laravel Breeze with the Blade views:

composer require laravel/breeze --dev
php artisan breeze:install blade

Next, install the required NPM packages:

npm install
npm run dev

Setting up the Database

Update your .env file with your Neon database credentials:

DB_CONNECTION=pgsql
DB_HOST=your-neon-hostname.neon.tech
DB_PORT=5432
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

After updating the .env file, run the database migrations:

php artisan migrate

Implementing Multi-Tenancy

Now that we have our basic setup, let's implement multi-tenancy in our application.

Creating the Tenant Model

Create a Tenant model:

php artisan make:model Tenant

Update the app/Models/Tenant.php file:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Stancl\Tenancy\Database\Models\Tenant as BaseTenant;
use Stancl\Tenancy\Contracts\TenantWithDatabase;
use Stancl\Tenancy\Database\Concerns\HasDatabase;
use Stancl\Tenancy\Database\Concerns\HasDomains;

class Tenant extends BaseTenant implements TenantWithDatabase
{
    use HasFactory, HasDatabase, HasDomains;

}

This model extends the base Tenant model provided by the tenancy package and implements the TenantWithDatabase interface. We've also defined the fillable attributes and custom columns for our tenant.

The HasDatabase and HasDomains traits provided by the tenancy package allow us to manage tenant-specific databases and domains. This essentially means that each tenant will have its own database and domain providing data isolation between tenants.

To learn more about the tenancy package event system and how to customize the tenant model, refer to the stancl/tenancy documentation.

Configuring Tenancy

Update the config/tenancy.php file to use our custom Tenant model:

'tenant_model' => \App\Models\Tenant::class,

Also, update the central domains configuration:

'central_domains' => [
    'laravel-multi-tenant-saas.test',
    'localhost',
    'example.com',
],

Replace the default central domains with your own domain names.

This is an important part as this is how the tenancy package will determine which domain belongs to which tenant and load the tenant-specific data accordingly.

Feel free to review the other configuration options in the config/tenancy.php file to customize the tenancy behavior based on your requirements.

Creating Tenant Migrations

The tenancy package has built-in event listeners that automatically run tenant-specific migrations when a tenant is created. For this we need to make sure that all of the tenant-specific migrations are in the database/migrations/tenant directory.

As each tenant will have its own database, the migrations in the tenant directory will be used to create tenant-specific tables in the tenant's database.

Start by copying the default User migration to the database/migrations/tenant directory:

cp database/migrations/0001_01_01_000000_create_users_table.php database/migrations/tenant

This will be the base migration for tenant-specific tables.

Implementing Tenant Routes

The tenancy package provides middleware to handle tenant-specific routes. This allows you to define routes that are accessible only to tenants and not to central domains.

Start by creating a new file routes/tenant.php for tenant-specific routes with the following content:

<?php

use Illuminate\Support\Facades\Route;
use Stancl\Tenancy\Middleware\InitializeTenancyByDomain;
use Stancl\Tenancy\Middleware\PreventAccessFromCentralDomains;

/*
|--------------------------------------------------------------------------
| Tenant Routes
|--------------------------------------------------------------------------
|
| Here you can register the tenant routes for your application.
| These routes are loaded by the TenantRouteServiceProvider.
|
| Feel free to customize them however you want. Good luck!
|
*/

Route::middleware([
    'web',
    InitializeTenancyByDomain::class,
    PreventAccessFromCentralDomains::class,
])->group(function () {
    Route::get('/', function () {
        return 'This is your multi-tenant application. The id of the current tenant is ' . tenant('id');
    });

    // Here you can add more tenant-specific routes
});

These routes will be loaded by the TenantRouteServiceProvider and will be accessible only to tenants. The InitializeTenancyByDomain middleware will set the current tenant based on the domain, and the PreventAccessFromCentralDomains middleware will prevent access from central domains.

For more information on how to customize the tenancy routes, refer to the stancl/tenancy documentation.

Implementing Tenant Creation

Create a controller for tenant registration, this would usually be done by the admin users of the application:

php artisan make:controller TenantController

Update the app/Http/Controllers/TenantController.php controller and implement the tenant registration process:

<?php

namespace App\Http\Controllers;

use App\Models\Tenant;
use Illuminate\Http\Request;

class TenantController extends Controller
{
    public function showRegistrationForm()
    {
        return view('tenant.register');
    }

    public function register(Request $request)
    {
        $request->validate([
            'domain' => 'required|string|max:255|unique:domains,domain',
        ]);

        $tenant = Tenant::create();
        $tenant->domains()->create(['domain' => $request->domain]);

        return redirect()->route('tenant.registered', $request->domain);
    }

    public function registered($domain)
    {
        return view('tenant.registered', compact('domain'));
    }
}

This controller handles tenant registration, creates a new tenant in the database, and sets up the tenant's domain. The TenancyServiceProvider will automatically map the tenancy events to the listener, which will create the tenant's database and run the tenant-specific migrations inside the database/migrations/tenant directory for the new tenant.

In a nutshell, the controller has three methods:

showRegistrationForm(): Displays the tenant registration form
register(): Registers a new tenant, which creates a new tenant record and domain
registered(): Displays a success message after registration

This controller will be used to manage tenant registration in our application. Allowing new tenants to register and create their own subdomain and database for their account.

Add routes for tenant registration in routes/web.php:

use App\Http\Controllers\TenantController;

Route::get('/register', [TenantController::class, 'showRegistrationForm'])->name('tenant.register');
Route::post('/register', [TenantController::class, 'register']);
Route::get('/registered/{domain}', [TenantController::class, 'registered'])->name('tenant.registered');

Create the corresponding views for tenant registration starting by creating the resources/views/tenant/register.blade.php file:

<x-guest-layout>
  <form method="POST" action="{{ route('tenant.register') }}">
    @csrf
    <div class="mt-4">
      <x-input-label for="domain" :value="__('Subdomain')" />
      <div class="flex">
        <x-text-input
          id="domain"
          class="mt-1 block w-full"
          type="text"
          name="domain"
          :value="old('domain')"
          required
        />
        <span class="text-gray-600 ml-2 mt-1">.example.com</span>
      </div>
    </div>

    <div class="mt-4 flex items-center justify-end">
      <x-primary-button class="ml-4"> {{ __('Register Tenant') }} </x-primary-button>
    </div>
  </form>
</x-guest-layout>

Then create the resources/views/tenant/registered.blade.php file to display the success message after registration:

<x-guest-layout>
  <div class="text-gray-600 mb-4 text-sm">
    {{ __('Your tenant has been registered successfully!') }}
  </div>

  <div class="mt-4 flex items-center justify-between">
    <div>
      Your tenant URL:
      <a
        href="https://{{ $domain }}.example.com"
        class="text-gray-600 hover:text-gray-900 text-sm underline"
        target="_blank"
        >https://{{ $domain }}.example.com</a
      >
    </div>
  </div>
</x-guest-layout>

This completes the tenant registration process. Tenants can now register and create their own subdomain and database for their account. In a real-world scenario, you would protect the registration routes with authentication middleware to ensure that only authorized admin users can create new tenants.

Verifying Tenant Registration

To verify that the registration process works, visit http://laravel-multi-tenant-saas.test/register and register a new tenant. After registration, you should see the success message with the tenant's domain.

Next go to your Neon dashboard and verify that the new tenant's database has been created:

SELECT * FROM tenants;

You should see the newly created tenant in the tenants table. You can also check the domains table to verify that the tenant's domain has been added:

SELECT * FROM domains;

And to verify that you actually have a separate database for the new tenant, use the \l command in the psql console to list all databases or the following SQL query:

SELECT datname FROM pg_database WHERE datistemplate = false;

The tenant's database should be listed in the results and it should be named tenant{tenant_id}.

The tenancy package allows you to configure the database naming convention for tenants. By default, the database name is tenant{tenant_id} where {tenant_id} is the ID of the tenant. You can also configure the package to use separate schemas instead of separate databases for tenants.

With that done, you've successfully implemented tenant registration in your multi-tenant SaaS application. Next let's implement the tenant onboarding process.

Implementing Tenant Onboarding

Now that you can register new tenants, let's create an onboarding process.

Each tenant will need to create an account to access their dashboard. The domain will be used to identify the tenant, so we'll use the domain as the tenant's subdomain, e.g., tenant1.example.com.

Create a new controller for tenant onboarding:

php artisan make:controller Tenant/OnboardingController

Update the app/Http/Controllers/Tenant/OnboardingController.php to handle the onboarding process:

<?php

namespace App\Http\Controllers\Tenant;

use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;

class OnboardingController extends Controller
{
    public function show()
    {
        if (User::count() > 0) {
            return redirect()->route('tenant.dashboard');
        }

        return view('tenant.onboarding');
    }

    public function store(Request $request)
    {
        $validated = $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|string|email|max:255|unique:users',
            'password' => 'required|string|min:8|confirmed',
        ]);

        $user = User::create([
            'name' => $validated['name'],
            'email' => $validated['email'],
            'password' => Hash::make($validated['password']),
        ]);

        auth()->login($user);

        return redirect()->route('tenant.dashboard')->with('success', 'Welcome to your new account!');
    }
}

Add routes for the onboarding process in routes/tenant.php inside the Route::middleware group for tenant routes:

use App\Http\Controllers\Tenant\OnboardingController;

Route::middleware([
    'web',
    InitializeTenancyByDomain::class,
    PreventAccessFromCentralDomains::class,
])->group(function () {
    // Existing routes
    // ...

    Route::get('/onboarding', [OnboardingController::class, 'show'])->name('tenant.onboarding');
    Route::post('/onboarding', [OnboardingController::class, 'store'])->name('tenant.onboarding.store');

});

Create the onboarding view in resources/views/tenant/onboarding.blade.php:

<x-guest-layout>
  <form method="POST" action="{{ route('tenant.onboarding.store') }}">
    @csrf

    <div>
      <x-input-label for="name" :value="__('Name')" />
      <x-text-input
        id="name"
        class="mt-1 block w-full"
        type="text"
        name="name"
        :value="old('name')"
        required
        autofocus
        autocomplete="name"
      />
    </div>

    <div class="mt-4">
      <x-input-label for="email" :value="__('Email')" />
      <x-text-input
        id="email"
        class="mt-1 block w-full"
        type="email"
        name="email"
        :value="old('email')"
        required
        autocomplete="username"
      />
    </div>

    <div class="mt-4">
      <x-input-label for="password" :value="__('Password')" />
      <x-text-input
        id="password"
        class="mt-1 block w-full"
        type="password"
        name="password"
        required
        autocomplete="new-password"
      />
    </div>

    <div class="mt-4">
      <x-input-label for="password_confirmation" :value="__('Confirm Password')" />
      <x-text-input
        id="password_confirmation"
        class="mt-1 block w-full"
        type="password"
        name="password_confirmation"
        required
        autocomplete="new-password"
      />
    </div>

    <div class="mt-4 flex items-center justify-end">
      <x-primary-button class="ml-4"> {{ __('Complete Setup') }} </x-primary-button>
    </div>
  </form>
</x-guest-layout>

For simplicity, we're extending the Breeze guest layout for the onboarding form. But you can customize the layout to match your application's design and even have different layouts for the onboarding process based on each tenant's requirements.

To test the onboarding process, visit http://tenant1.example.com/onboarding and complete the onboarding form. After submitting the form, you should be redirected to the tenant dashboard which we'll implement next.

Implementing Tenant Dashboard

Create a new controller for the tenant dashboard:

php artisan make:controller Tenant/DashboardController

Update the app/Http/Controllers/Tenant/DashboardController.php to display the tenant dashboard:

<?php

namespace App\Http\Controllers\Tenant;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;

class DashboardController extends Controller
{
    public function index()
    {
        return view('tenant.dashboard');
    }
}

Create the dashboard view in resources/views/tenant/dashboard.blade.php:

<x-app-layout>
  <x-slot name="header">
    <h2 class="text-gray-800 text-xl font-semibold leading-tight">{{ __('Dashboard') }}</h2>
  </x-slot>

  <div class="py-12">
    <div class="mx-auto max-w-7xl lg:px-8 sm:px-6">
      <div class="overflow-hidden bg-white shadow-sm sm:rounded-lg">
        <div class="text-gray-900 p-6">{{ __("You're logged in!") }}</div>
      </div>
    </div>
  </div>
</x-app-layout>

Add a route for the tenant dashboard in routes/tenant.php inside the Route::middleware group for tenant routes:

use App\Http\Controllers\Tenant\DashboardController;

Route::middleware([
    'web',
    InitializeTenancyByDomain::class,
    PreventAccessFromCentralDomains::class,
])->group(function () {
    // Existing routes
    // ...
    Route::get('/dashboard', [DashboardController::class, 'index'])->name('tenant.dashboard');

});

To test the tenant dashboard, visit http://tenant1.example.com/dashboard after completing the onboarding process. You should see the dashboard view with a welcome message.

You can also check the users table in the tenant's database to verify that the user account created during onboarding has been added:

SELECT * FROM users;

This will show you the user account created during the onboarding process for that specific tenant in the tenant's database rather than the central database.

Conclusion

In this tutorial, we've built a simple multi-tenant application using Laravel and Neon. We've covered:

Setting up the project and implementing multi-tenancy
Creating a tenant registration process
Implementing tenant onboarding
Adding a tenant dashboard for individual tenants

This implementation provides a foundation for building more complex SaaS applications with Laravel and Neon. You can further expand on this system by:

Adding more features to the tenant dashboard
Implementing billing and subscription management
Enhancing security with two-factor authentication
Adding more tenant-specific customizations

Using the stancl/tenancy package along with Neon, each tenant will have its own database. Thanks to Neon's autoscaling feature, you can easily scale your application as you onboard more tenants.

There are other packages and tools available to help you build multi-tenant applications with Laravel. You can explore these options based on your requirements and choose the one that best fits your needs. Some of the popular packages include:

Additional Resources

How to use Synthetic Data to catch more bugs with Neosync

Rishi Raj Jain — Thu, 19 Dec 2024 15:06:37 +0000

A guide to developing robust, scalable and secure applications with Synthetic Data

In today’s world, developers are under more pressure than ever to develop robust, scalable and secure applications that have no bugs and are performant. Users want their applications and software to work flawlessly and any sign of a bug or disruption in workflow can lead to a frustrated or even lost user.

The challenge is that it’s really hard and time consuming to manually write test cases and test data in order to try to catch every edge case. Even then, it’s not perfect! A lot of teams will use their production data to test locally but this has a lot of privacy and security risks and by definition, you’re only using data that you’ve been able to successfully process. Which means that you’re not catching additional edge cases.

So then, as a developer, how can you be sure that you’re writing resilient code and developing a resilient application if you only have “happy path” data? The answer is that you really can’t. You need a better way to test and validate your systems.

This is where synthetic data can help you catch more bugs before you ship to production.

What is Synthetic Data?

Synthetic data is artificially generated data that is statistically and structurally just like real-world data, without containing any actual sensitive or personal information. Synthetic data is typically created using a combination of machine learning models and simulation algorithms.

This data can be nearly statistically identical to the source data set. For example, if the source data set has an age column with a range of 70 and a mean of 25.8, we can use machine learning models to create an identical column of brand new data that also has a range of 70 and mean of 25.8. Machine learning models such as CTGAN are great at learning the statistical properties of a set of data and replicating them with brand new data.

Further, with synthetic data, we can replicate the structure of the source data set. This means preserving the referential integrity or primary key and foreign key relationships, circular dependencies and other constraints.

Using a combination of machine learning and other algorithms we can replicate this structure in a data set such that you could easily import it into your current database without any problems. This is the power of synthetic data. The ability to create a data set that is statistically and structurally just like your production data without any of the privacy and security concerns.

Using Synthetic data to catch more bugs

Synthetic data can be a powerful tool to catch more bugs before they get reported in production. Let’s take a look at three of the most common use cases.

Generating diverse data to catch edge cases

Test driven development is more popular than ever which is a great thing for application resiliency. But the truth is that manually writing test cases can be tedious and really hard to anticipate every edge case. Most developers will test the happy path and then some edge cases before moving on.

This is where synthetic data can help. By generating a large and diverse set of data that would have taken days to manually write, you can check to make sure that your application can handle many different data types, formats and values.

The best part is that generating data can be really fast. For example, using Neosync, you can generate 10,000 rows of data for your Neon database in less than 30 seconds. It’s as simple as creating a connection to your Neon database and creating a job in Neosync. For more information, check out this blog post.

Ultimately, the end goal is that you can catch more bugs in your development and staging environments. Which means that you can ship a more resilient application.

Using Synthetic data for automated testing

Synthetic data can take automated testing to the next level. Developers can set up automated test suites in their CI pipelines and point to a database that is hydrated with synthetic data to test their applications. Instead of using the same stale data set, developers can have brand new data generated every time, increasing the chances that they catch a bug before they ship to production.

If they do catch a bug, then they can replicate that bug locally by hydrating a development or local database with the same data set and start to debug the error. This workflow of testing locally with synthetic data and then testing in CI with synthetic data, is a great way to catch bugs and gain confidence in your application’s resiliency.

Using Synthetic data to for performance testing

The last thing any developer wants is for their application to crash during a period of high-traffic. Imagine if Shopify crashed during Black Friday? For a company like Shopify, the problem is that they have a lot of sensitive data and can’t move their production data around easily without taking on a lot of privacy and security risk. So how do they get enough data for performance testing without worrying about privacy or security?

This is a perfect use case for synthetic data. Because synthetic data is artificially generated, you can create as much of it as you’d like. This makes performance testing a breeze and eliminates the privacy and security risks of handling production data. Just define how much data you need and then let the system create that data for you. You can then automatically ingest that into your application and monitor any performance issues without having to wait to see if it fails in production.

Conclusion

Synthetic data is a great tool that developers can use to catch more bugs and ship more resilient applications. It’s a powerful way to test your applications functionality and performance without any of the privacy and security concerns of production data. The great thing is that synthetic data tools and platforms are only getting better, higher fidelity and faster which makes it even more compelling for developers to start considering it as part of their core workflow.

6 Essential Features Every Web Starter Kit Should Include

Rishi Raj Jain — Sun, 27 Oct 2024 21:19:24 +0000

Need a web starter kit that has everything? Here's what you need to know in 30 seconds:

A useful web starter kit needs these 6 core features:

Feature	What You Get	Popular Tools
User Login and Account System	User auth, sessions, access control	Authjs.dev, Lucia, Clerk
Dev Tools	Code editor, version control, linting	VS Code, Prettier, ESLint
Data Management Tools	Database setup, state management	MongoDB, PostgreSQL, Firestore, Redis, SQLite
CSS and Design Setup	Styling framework, design system	Tailwind CSS, Bootstrap CSS
API Tools	Endpoints, auth, security	Authjs.dev, JWT (jsonwebtoken)
Security Setup	SSL, headers, input validation	HTTPS, CSP, Authorization

Why this matters: A good starter kit cuts development time by 40-60% and helps you avoid common setup mistakes.

Quick facts:

Setup time: 24-48 hours
Works with: Astro, SvelteKit, Next.js
Browser support: All modern browsers
Learning curve: 1 day for initial setup

The LaunchFast Astro, Next.js and SvelteKit starter kits includes all these features pre-configured. Purchase, clone and start launching!

1. User Login and Account System
2. Basic Dev Tools Setup
3. Data Management Tools
4. CSS and Design Setup
5. API Setup and Tools
6. Basic Security Setup
Website Launch Checklist
Wrap-up

1. User Login and Account System

Every web app needs a solid login system. Here's what your starter kit should include for managing users:

Component	Purpose	Common Implementation
Authentication	Verify user identity	Email/password, social logins
Session Management	Track user state	Cookies, database storage
Password Security	Protect user data	Password hashing

Your basic login system needs to handle:

Sign up with email checks
Password resets
Login/logout flow
Session timeouts

Want to skip the heavy lifting? Here are some popular pre-built options:

Auth Provider	Features	Best For
Lucia	Encrypted cookies, stateless sessions	Simple setups
Iron Session	Encrypted cookies, stateless sessions	Simple setups
Authjs.dev	Built-in API routes, database sessions	Next.js, SvelteKit projects
Clerk	Social logins, customizable UI	Large applications
Auth0	Social logins, customizable UI	Large applications

Let's break this down with an online course platform:

A student logs in. The system checks if they've paid. If yes, they get access to their courses. The system tracks their progress and keeps them logged in.

To keep things secure:

Hash those passwords
Use HTTPS for auth
Lock down your cookies

The LaunchFast Astro, Next.js and SvelteKit starter kits come with all this built-in. You get a secure auth system without the setup headaches.

2. Basic Dev Tools Setup

Here's what you need to start coding right away:

Tool Category	Tools	Purpose
Code Editor	VS Code	Write and debug code
Version Control	Node.js, npm/yarn	Manage packages
Code Quality	ESLint, Prettier	Keep code clean
Type Safety	TypeScript	Catch errors early

1. VS Code: Your Code Home

VS Code is the go-to editor for 73% of developers. Here are the must-have extensions:

Extension	Downloads	What You Get
Live Server	46M+	See changes instantly
GitHub Copilot	14.6M+	Get AI code suggestions
GitLens	30M+	Track code changes
Prettier	42M+	Format code automatically

2. Node.js: Your Build Foundation

# Set up Node
echo "v20.10.0" > .nvmrc
nvm use

# Start your project
npm init -y

3. TypeScript: Add Type Safety

# Get TypeScript ready
npm install --save-dev typescript @types/node @tsconfig/node20

# Add to package.json
{
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch"
  }
}

4. Make Your Code Look Good

// .prettierrc
{
  "tabWidth": 2,
  "trailingComma": "es5",
  "semi": true,
  "singleQuote": true
}

Pick your starter framework:

Framework	Command
Astro	npm create astro@latest
SvelteKit	npx sv create my-app
Next.js	npx create-next-app@latest

Add this for better debugging:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Server",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    }
  ]
}

3. Data Management Tools

Here's what you need to know about databases for your web starter kit:

Database Type	Best For	Used By	Key Features
MySQL	Structured data	Facebook, Twitter	SQL queries, ACID compliance
MongoDB	Unstructured data	Uber, eBay	Document-based, high scalability
PostgreSQL	Complex queries	Financial apps	Data integrity, JSON support
Redis	Caching, sessions	Instagram, GitHub	In-memory, fast performance
Firestore	NoSQL, real-time	Google, Firebase	Real-time data, offline support
SQLite	Embedded database	Mobile apps, IoT	Lightweight, self-contained

State management boils down to your framework choice:

Framework	Tool	Setup Command
Astro	Nanostores	`import { atom } from 'nanostores'`
Svelte	Built-in stores	`import { writable } from 'svelte/store'`
Next.js	Zustand	`npm i zustand`

Here's how to set up a Svelte store:

// store.js
import { writable } from 'svelte/store';

export const userData = writable({
  name: '',
  email: '',
  preferences: {}
});

SQL vs NoSQL: Quick Guide

Factor	SQL Databases	NoSQL Databases
Data Structure	Fixed schema	Flexible schema
Scaling	Vertical	Horizontal
Query Language	SQL	Various
Use Case	Banking, CRM	Real-time data, IoT

Here's a basic CRUD setup:

// api/users.js
export async function getUser(id) {
  return await db.query('SELECT * FROM users WHERE id = ?', [id])
}

export async function createUser(data) {
  return await db.query('INSERT INTO users SET ?', data)
}

Keep your files organized:

Folder	Contents	Purpose
`/db`	Database configs	Connection setup
`/api`	API routes	Data endpoints
`/stores`	State management	Client-side data

4. CSS and Design Setup

Let's look at the top CSS frameworks you can pick from:

Framework	Size (gzipped)	Learning Time	Best For	Used By
Bootstrap	16KB	1-2 days	Rapid prototyping	Twitter, Spotify
Tailwind	508.7kB	3-4 days	Custom designs	Shopify, OpenAI
Foundation	34.7 KB	2-3 days	Enterprise apps	-

Want to get started? Here's the basic setup:

# Bootstrap
npm install bootstrap@5.3.3

# Tailwind
npm install -D tailwindcss
npx tailwindcss init

For Tailwind, drop this into your CSS:

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

Here are some tools that'll make your CSS work easier:

Tool	Purpose	Price
CSS Grid Generator	Layout creation	Free
PurifyCSS	Remove unused CSS	Free
CSS Scan	Copy styles from sites	$100 lifetime
Tailscan	Tailwind inspector	$59/year

Here's what a basic Tailwind component looks like:

const Nav = () => (
  <nav className="fixed w-full bg-white shadow-lg">
    <div className="max-w-7xl mx-auto px-4">
      <div className="flex justify-between h-16">
        <Logo />
        <MenuItems />
      </div>
    </div>
  </nav>
)

Some numbers that might interest you:

Tailwind as a low-level CSS framework has become my preferred styling solution. It has solved most of the drawbacks I have encountered in my journey through different CSS solutions. - Rishi Raj Jain, LaunchFast

Here's how to organize your design files:

Folder	Contents
`/styles`	Global CSS
`/components`	UI components

5. API Setup and Tools

Here's what you need to set up APIs in your next project:

Component	Purpose	Setup Command
TLS/SSL	Message encryption	`openssl req -x509 -nodes -days 365 -newkey rsa:2048`
OAuth2	User authentication	`npm install oauth2-server`
JWT	Token handling	`npm install jsonwebtoken`
NextAuth.js	Social login	`npm install next-auth`

Let's look at different auth methods:

Auth Method	Setup Time	Security Level	Best For
API Keys	30 mins	Basic	Internal tools
OAuth 2.0	2-3 hours	High	Public apps
JWT	1 hour	Medium	Mobile apps
mTLS	4-5 hours	Very High	Enterprise

The numbers don't lie:

Here's the RIGHT way to handle API keys:

// BAD - Don't do this
const apiKey = "sk_test_123456789";

// GOOD - Do this instead
const apiKey = process.env.API_KEY;

Want Google OAuth in your Next.js project? Here's how:

import NextAuth from 'next-auth'  
import GoogleProvider from 'next-auth/providers/google'

export default NextAuth({  
  providers: [  
    GoogleProvider({  
      clientId: process.env.GOOGLE_ID,  
      clientSecret: process.env.GOOGLE_SECRET,  
    }),  
  ],  
})

Keep your files organized like this:

Folder	Contents
`/api`	API routes
`/auth`	Auth config
`/middleware`	API middleware
`/lib/utils`	Helper functions

6. Basic Security Setup

Here's how to protect your web app from common threats:

Security Feature	Purpose	Implementation
SSL Certificate	Encrypts data in transit	Install from trusted CA, force HTTPS
Security Headers	Browser protection rules	Set CSP, HSTS, X-Frame-Options
Input Validation	Prevents injection attacks	Use zod/Valibot for schema checks
Secure Cookies	Protects session data	Set HttpOnly and Secure flags
Environment Variables	Hides sensitive data	Store API keys, credentials in .env

Add these headers to your Next.js app:

// next.config.js
const securityHeaders = [
  {
    key: 'Strict-Transport-Security',
    value: 'max-age=63072000'
  },
  {
    key: 'X-Frame-Options',
    value: 'DENY'
  },
  {
    key: 'Content-Security-Policy',
    value: "default-src 'self'"
  }
]

Here's how to lock down your API routes:

export default function handler(req, res) {
  // Block non-POST requests
  if (req.method !== 'POST') {
    return res.status(405).end()
  }

  // Check auth token
  const token = req.headers.authorization
  if (!isValidToken(token)) {
    return res.status(401).json({
      error: 'Invalid token'
    })
  }
}

Know these attacks and how to stop them:

Attack Type	Risk	Solution
XSS	Script injection	CSP headers, input sanitization
CSRF	Fake requests	CSRF tokens, SameSite cookies
SQL Injection	DB compromise	Parameterized queries
DoS	Server overload	Rate limiting, CDN protection

Here's what you MUST do first:

Switch to HTTPS: Block all HTTP traffic
Add Security Headers: Set up CSP and other browser rules
Check All Input: Filter form data and API requests
Lock Down Cookies: Enable HttpOnly and Secure flags
Protect Your Secrets: Use environment variables

Test your setup with:

Mozilla Observatory
Security Headers
SSL Labs Server Test

Your security work isn't done after setup. Check for dependency updates every week and run security scans each month.

Website Launch Checklist

Here's what you need to get your website up and running:

Launch Phase	Tools	Purpose
Speed	Google PageSpeed Insights, WebPageTest, GTMetrix	Load time checks
Security	SSL Certificate, HTTPS	Data safety
SEO	XML Sitemap, robots.txt	Google indexing
Analytics	Wide Angle Analytics, Google Analytics, Pirsch Analytics, etc.	User tracking

Pick your hosting:

Hosting Provider	Features	Best For
Fly.io	Global deployment, automatic scaling, Docker support	Apps needing low latency worldwide
Vercel	Serverless functions, easy integration with Next.js, automatic scaling	Frontend frameworks and static sites
Netlify	Continuous deployment, serverless functions, form handling	JAMstack sites and static web apps
AWS Amplify	Full-stack development, easy integration with AWS services, CI/CD	Complex applications needing AWS infrastructure

Must-do checks:

Test every form and payment flow
Click all links
Check SSL setup
Send sitemap to Google
Create a 404 page

Speed things up:

Task	Tool	Result
Compress images	`.webp` format	25-35% smaller
Shrink code	Terser	30-50% smaller
Use CDN	Cloudflare/Vercel	Faster loading
Set cache	Browser cache	Quick returns

Here's why speed matters: Over half your visitors will leave if your site takes more than 3 seconds to load.

Wrap-up

Your starter kit should make life easier. Pick tools that play nice together and fit what you're building.

Comparing local-first frameworks and approaches

Rishi Raj Jain — Mon, 21 Oct 2024 16:21:31 +0000

Any sufficiently advanced technology is indistinguishable from magic.

Cloud applications can feel like magic. You write text in a Google Doc on your laptop, and it magically appears in the doc on your phone. Or you’re working on some code in an online IDE like Replit, and your entire team can build together.

But, like magic, we all know a lot is going on under the surface that we’re not supposed to see. And, like magic, when it goes wrong, it goes horribly wrong. Such as when you’re writing a Google Doc, the network fails, and the doc hangs. You can’t edit it because the document can’t be updated from the cloud. Suddenly, you wish for Windows 95 and the luxury of local.

Luckily, local isn’t a disappearing technology. In fact, local is making a renaissance with local-first frameworks that put your data in your hands first. If the cloud is there, great. If not, ¯_(ツ)_/¯. This is such a nascent field that several local-first frameworks are being built to approach this problem from different sides. Here, we want to highlight a few to give you a feel for what to look for in local-first applications.

Merging Data with CRDTs

In 2019, University of Cambridge computer scientist Martin Kleppmann (of Designing Data-Intensive Applications fame) and authors from digital research lab Ink & Switch published a manifesto titled, “Local-first software: you own your data, in spite of the cloud.”

The manifesto laid out their thinking on how the cloud-first data storage model had gone awry. First, you get the issue mentioned above–cloud apps become unusable offline, limiting usability. But the problems go beyond that. When data is stored primarily in the cloud, users become “borrowers” of their own data. The service provider has ultimate control over access and preservation. It can be difficult to migrate data between cloud services, and if the cloud service shuts down, users lose access to their data and work.

The manifesto proposed seven ideals for local-first software:

No spinners: Fast performance by working with local data
Multi-device: Seamless sync across all user devices
Offline: Full read/write functionality without internet access
Collaboration: Real-time collaborative editing for multiple users
Longevity: Access and edit data for decades, outliving servers
Privacy: Encrypted data that’s not accessible to service providers
User control: Ownership of data, including the ability to copy, modify, and delete

They proposed a number of technical concepts to achieve these aims, with the critical one being the Conflict-Free Replicated Data Type, or CRDT. CRDTs are data structures that allow multiple replicas of a dataset to be updated independently and concurrently without coordination between the replicas while ensuring that all replicas eventually converge to the same state. This makes them particularly well-suited for local-first software architectures. The key properties of CRDTs include:

** Strong eventual consistency.** All replicas will converge to the same state given the same set of updates, regardless of order received
** Commutativity.** The order of applying updates does not affect the final state
Associativity. Updates can be grouped and applied in any order

Say you have a collaborative text document that two people are working on. Each can work offline, and CRDTs will take care of merging. They assign unique identifiers to each character or operation, allowing the system to track and merge changes intelligently. For example, if one user inserts text at the beginning of the document while another adds content at the end, the CRDT algorithm can seamlessly integrate both changes without conflict.

Ink & Switch released automerge to automatically achieve this merge. If you have two documents you are collaboratively editing, you can use automerge to make concurrent changes.

import { next as Automerge } from "@automerge/automerge"

let doc = Automerge.from({text: "hello world"})

// Fork the doc and make a change
let forked = Automerge.clone(doc)
forked = Automerge.change(forked, d => {
    // Insert ' wonderful' at index 5, don't delete anything
    Automerge.splice(d, ["text"], 5, 0, " wonderful")
})

// Make a concurrent change on the original document
doc = Automerge.change(doc, d => {
    // Insert at the start, delete 5 characters (the "hello")
    Automerge.splice(d, ["text"], 0, 5, "Greetings")
})

// Merge the changes
doc = Automerge.merge(doc, forked)

console.log(doc.text) // "Greetings wonderful world"

This approach enables true local-first collaboration, where users can work offline and sync their changes when they reconnect, without the need for a central server to arbitrate conflicts.

Syncing Data with PouchDB

“The Database that Syncs!” shouts the PouchDB homepage. PouchDB is another new local-first/sync database. PouchDB is a JavaScript database that runs in the browser, allowing developers to create applications that work offline and sync with server-side databases when online. It’s designed to be compatible with (and is inspired by) Apache’s NoSQL CouchDB.

The core principles of PouchDB align well with the local-first manifesto:

Offline-first: Works entirely offline, syncing when a connection is available
** Multi-device sync:** Seamlessly syncs data across devices
**Open source: **Allows for community contributions and audits
Cross-platform: Runs in browsers, Node.js, and mobile devices

PouchDB uses a document-based data model, where each document is a JSON object. Here’s a simple example of creating and querying a PouchDB database:

// Create a database
var db = new PouchDB('my_database');

// Add a document
db.put({
  _id: 'mittens',
  name: 'Mittens',
  species: 'cat',
  age: 3
}).then(function () {
  // Find all documents where species is 'cat'
  return db.find({
    selector: {species: 'cat'}
  });
}).then(function (result) {
  console.log(result.docs);
}).catch(function (err) {
  console.log(err);
});

One of PouchDB’s key features is its sync protocol. When online, PouchDB can sync with a CouchDB server, allowing for real-time collaboration:

var localDB = new PouchDB('my_database');
var remoteDB = new PouchDB('http://example.com/my_database');

localDB.sync(remoteDB, {
  live: true,
  retry: true
}).on('change', function (change) {
  console.log('Data changed:', change);
}).on('error', function (err) {
  console.log('Sync error:', err);
});

PouchDB doesn’t use CRDTs for conflict resolution. Instead, it uses a deterministic algorithm based on revision history. When conflicts occur, PouchDB chooses a winning revision and stores the others as conflicts, which can be accessed and resolved manually. If you want to nerd out, here’s a good read on how CouchDB provides eventual consistency.

While PouchDB provides a robust solution for offline-first apps, it’s not without challenges. Large datasets can impact performance. And like other local-first solutions, developers need to carefully consider data modeling and conflict resolution strategies.

PouchDB shows us that local-first isn’t just about new, bleeding-edge tech–it’s about reimagining existing databases for a world where offline is the norm, not the exception.
Sync from Postgres with ElectricSQL

ElectricSQL is especially exciting to us at Neon because it uses Postgres as the underlying data store. It is one level broader than a local-first solution: The core component of ElectricSQL is a service called a Sync Engine that runs on your servers between local devices and your Postgres database. So you can use ElectricSQL as a key component of a local-first architecture but it doesn’t solve all your needs.

The ElectricSQL service listens for changes in your database using Postgres logical replication and efficiently syncs little subsets of data into connected local apps.

The sync engine is only the server-side component though, you still need a local component to consume the data. ElectricSQL has a Typescript client that gives you basic functionality for consuming data from the sync engine:

import { ShapeStream, Shape } from '@electric-sql/client'

const stream = new ShapeStream({
  url: `${BASE_URL}/v1/shape/foo`,
})
const shape = new Shape(stream)

// Returns promise that resolves with the latest shape data once it's fully loaded
await shape.value

// passes subscribers shape data when the shape updates
shape.subscribe(shapeData => {
  // shapeData is a Map of the latest value of each row in a shape.
}

note
If you're using ElectricSQL with Neon, make sure to enable logical replication on your database via the Neon UI to make it work.

More examples of local-first with ElectricSQL can be found in the examples directory of their repo. https://github.com/electric-sql/electric/tree/main/examples

Local By Default

If you’ve ever wondered how Linear, Figma, or Excalidraw work, this is it. Local-first approaches are changing how we think about data ownership and application architecture. They’re not just solving the offline problem; they’re making us rethink the entire user-data relationship.

This is hardly an exhaustive list. While most local-first frameworks are roughly following one of the above approaches, each has a fun implementation that might make it the best option for you. To take your research further, here’s an evaluation paradigm for assessing local-first solutions, and here’s a list of local-first tools that you can explore. By putting data back in users’ hands, these frameworks are paving the way for more resilient, privacy-respecting, and user-centric applications.

Developing a Scalable Flask Application with Neon Postgres

Rishi Raj Jain — Tue, 15 Oct 2024 10:53:23 +0000

Building scalable web applications requires careful planning and the right tools. Flask is a Python web framework well-suited for building small to large web applications. It provides flexibility and extensibility, making it a popular choice for developers.

In this guide, we'll walk through developing a Flask application that uses Neon Postgres. We'll cover setting up the project structure, defining models, creating routes, and handling database migrations. We'll also explore frontend development using Tailwind CSS for responsive styling.

Prerequisites

Python 3.7 or later installed
Node.js 18 or later
A Neon account for Postgres hosting
Basic familiarity with Flask and SQLAlchemy

Project Setup

Create a new directory and set up a virtual environment:

   mkdir flask-neon-app
   cd flask-neon-app
   python -m venv venv
   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`

Install required packages:

   pip install flask flask-sqlalchemy psycopg2-binary python-dotenv flask-migrate

Create a requirements.txt file for package management:

   pip freeze > requirements.txt

This file will help you manage dependencies and ensure consistent environments across development and deployment.

Create a .env file for environment variables:

   DATABASE_URL=postgresql://user:password@your-neon-host:5432/your-database

Replace user, password, your-neon-host, and your-database with your Neon Postgres credentials.

Application Structure

For small applications, you can keep all code in a single file. However, as your application grows, it's best to organize your code into separate modules. It is a good practice to separate models, routes, services, and utilities into different directories.

A typical Flask application structure might look like this:

flask-neon-app/
├── app/
│   ├── __init__.py
│   ├── models/
│   ├── routes/
│   ├── services/
│   ├── static/
│   │   └── css/
│   ├── templates/
│   └── utils/
├── config.py
├── requirements.txt
├── run.py
└── tailwind.config.js

This structure separates concerns and makes it easier to maintain and scale your application. The app directory contains the core application logic, while other files and directories handle configuration, dependencies, and frontend assets.

Database Configuration

You can think of the app/__init__.py file as the entry point for your Flask application. It initializes the Flask app, sets up the database connection, and registers blueprints for routing.

By adding the __init__.py file, you transform the app directory into a Python package. This allows you to import modules from the app package in other files.

The app directory name is a common convention for Flask applications, but you can choose a different name if you prefer based on your project needs.

With that in mind, let's set up the database connection and initialize the Flask app. In app/__init__.py, add the following code:

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from dotenv import load_dotenv
import os

load_dotenv()

db = SQLAlchemy()
migrate = Migrate()

def create_app():
    app = Flask(__name__)
    app.config['SQLALCHEMY_DATABASE_URI'] = os.getenv('DATABASE_URL')
    app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

    db.init_app(app)
    migrate.init_app(app, db)

    # Register blueprints here
    from app.routes import user_routes
    app.register_blueprint(user_routes.user_bp)

    return app

This setup initializes Flask, SQLAlchemy, and Flask-Migrate. It loads the database URL from the environment variables and disables SQLAlchemy's modification tracking for better performance.

Blueprints are a way to organize related routes and views in Flask applications. We will cover blueprints and routes in the next sections.

To learn more about Flask-Migrate, check out the Managing database migrations and schema changes with Flask and Neon Postgres guide.

Model Definition

In web applications, models represent the data structure and relationships in your database. In the context of Flask and SQLAlchemy, models are Python classes that map to database tables and also allow you to define the schema and relationships between tables.

As an example of a typical model definition, let's create a User model in app/models/user.py:

from app import db
from datetime import datetime

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
    created_at = db.Column(db.DateTime, default=datetime.utcnow)

    def __repr__(self):
        return f'<User {self.username}>'

    def to_dict(self):
        return {
            'id': self.id,
            'username': self.username,
            'email': self.email,
            'created_at': self.created_at.isoformat()
        }

This model defines a User with username, email, and created_at fields. The __repr__ method provides a string representation of the model instance for debugging purposes and logging. The to_dict method allows easy serialization of the model to JSON which is useful when returning data from API endpoints.

Route Creation with Blueprints

In Flask, blueprints are a good way to organize your application into components. They allow you to group related routes, view functions, templates, and static files. Blueprints help in structuring large applications allowing you to separate different functional areas of your project.

If you're familiar with Laravel, blueprints in Flask serve a similar purpose to Laravel's controllers and route groups, allowing you to logically organize your routes and associated functionality.

Some of the main benefits of using blueprints in Flask include grouping related routes together, organizing your application into modular components, and avoiding naming conflicts between different parts of your application.

Here's an expanded example of how to use blueprints in a Flask application, in a file named app/routes/user_routes.py for user-related routes:

from flask import Blueprint, jsonify, request, render_template, redirect, url_for
from app.models.user import User
from app import db

# Create a blueprint named 'user' with a URL prefix '/user'
user_bp = Blueprint('user', __name__, url_prefix='/user')

# Route for creating a new user (HTML form submission)
@user_bp.route('/create', methods=['POST'])
def create_user():
    data = request.form
    new_user = User(username=data['username'], email=data['email'])
    db.session.add(new_user)
    db.session.commit()
    return redirect(url_for('user.list_users'))

# Route for displaying all users (HTML)
@user_bp.route('/list', methods=['GET'])
def list_users():
    users = User.query.all()
    return render_template('users.html', users=users)

# API route for retrieving all users (JSON)
@user_bp.route('/api/list', methods=['GET'])
def get_users_api():
    users = User.query.all()
    return jsonify([user.to_dict() for user in users])

# Route for displaying a single user (HTML)
@user_bp.route('/<int:user_id>', methods=['GET'])
def get_user(user_id):
    user = User.query.get_or_404(user_id)
    return render_template('user_detail.html', user=user)

# API route for retrieving a single user (JSON)
@user_bp.route('/api/<int:user_id>', methods=['GET'])
def get_user_api(user_id):
    user = User.query.get_or_404(user_id)
    return jsonify(user.to_dict())

Let's break down this code:

We import necessary modules and create a blueprint named 'user' with a URL prefix '/user'. This prefix will be prepended to all routes defined within this blueprint which helps in organizing routes into logical groups. If you have multiple blueprints, each can have its own URL prefix.
create_user(): This route handles POST requests to create a new user. It reads form data, creates a new User instance, adds it to the database session, and commits the transaction. It then redirects to the list_users() route.
list_users(): This route displays all users in HTML format. It queries all users from the database and renders a template with the user data.
get_users_api(): This API route returns all users in JSON format. It queries all users from the database, converts them to dictionaries using the to_dict() method, and returns a JSON response.
get_user(): This route displays details of a single user in HTML format. It retrieves a user by ID or returns a 404 error if the user doesn't exist.
get_user_api(): This API route returns details of a single user in JSON format. It retrieves a user by ID or returns a 404 error if the user doesn't exist.

To use this blueprint in your main Flask application, you would register it like this in app/__init__.py which we've seen earlier:

from flask import Flask
from app.routes.user_routes import user_bp

app = Flask(__name__)
app.register_blueprint(user_bp)

This structure allows you to organize related routes together, making your application more modular and easier to maintain as it grows.

Frontend with Tailwind CSS and Templates

Tailwind CSS is a utility-first CSS framework that allows you to rapidly build custom user interfaces. It provides low-level utility classes that let you build completely custom designs without ever leaving your HTML.

To integrate Tailwind CSS with Flask templates, you can follow these steps:

Install Tailwind CSS:

   npm init -y
   npm install tailwindcss
   npx tailwindcss init

This initializes a new Node.js project, installs Tailwind CSS, and creates a basic Tailwind configuration file.

Update the Tailwind CSS configuration file tailwind.config.js to include your HTML templates:

   module.exports = {
     content: ['./app/templates/**/*.html'],
     theme: {
       extend: {},
     },
     plugins: [],
   };

This configuration tells Tailwind to scan your HTML templates for classes to include in the final CSS output. The extend key allows you to customize Tailwind's default theme.

Create app/static/css/main.css:

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

This file imports Tailwind's base styles, component classes, and utility classes. It serves as the entry point for Tailwind to inject its styles.

Compile Tailwind CSS:

   npx tailwindcss -i ./app/static/css/main.css -o ./app/static/css/output.css --watch

This command compiles your Tailwind CSS file and watches for changes. This allows you to keep your CSS file as small as possible by only including the styles you use in your templates, which is important for performance as your application grows, and unnecessary styles can slow down your site.

The --watch flag ensures that the CSS is recompiled whenever you make changes to your HTML files. This is useful for rapid development and live reloading.

Create a base template in app/templates/base.html:

   <!doctype html>
   <html lang="en">
     <head>
       <meta charset="UTF-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>{% block title %}Flask Neon App{% endblock %}</title>
       <link rel="stylesheet" href="{{ url_for('static', filename='css/output.css') }}" />
     </head>
     <body class="bg-gray-100">
       <nav class="bg-blue-500 p-4 text-white">
         <div class="container mx-auto">
           <a href="/" class="text-2xl font-bold">Flask Neon App</a>
         </div>
       </nav>
       <main class="container mx-auto mt-8">{% block content %}{% endblock %}</main>
     </body>
   </html>

This base template sets up the basic structure of your HTML pages. It includes:

A title block that can be overridden in child templates
A link to the compiled Tailwind CSS file
A simple navigation bar with Tailwind classes for styling
A main content area with a block that child templates can fill thanks to Jinja2 template inheritance

Create app/templates/users.html:

   {% extends "base.html" %} {% block title %}Users{% endblock %} {% block content %}
   <h1 class="mb-4 text-3xl font-bold">Users</h1>
   <div class="rounded bg-white p-4 shadow-md">
     <form action="{{ url_for('user.create_user') }}" method="post" class="mb-4">
       <input type="text" name="username" placeholder="Username" required class="mr-2 border p-2" />
       <input type="email" name="email" placeholder="Email" required class="mr-2 border p-2" />
       <button type="submit" class="bg-blue-500 rounded px-4 py-2 text-white">Add User</button>
     </form>
     <ul>
       {% for user in users %}
       <li class="mb-2">{{ user.username }} ({{ user.email }})</li>
       {% endfor %}
     </ul>
   </div>
   {% endblock %}

This template extends the base template using {% extends "base.html" %} and provides specific content for the users page. It includes:

A form for adding new users, styled with Tailwind classes
A list of existing users, also styled with Tailwind
Jinja2 template syntax for dynamic content (e.g., {% for user in users %})

Tailwind CSS and Jinja2 templates give you the flexibility to create your frontend design while keeping your codebase organized and maintainable. This approach allows you to build responsive and visually appealing web applications with ease.

Database Migrations

Database migrations are an important part of managing your application's database schema over time. They allow you to evolve your database structure incrementally, keeping it in sync with your application's models. We will be using Flask-Migrate, which is an extension for Flask that handles SQLAlchemy database migrations using Alembic, makes this process straightforward.

Here's a quick guide to setting up and using Flask-Migrate for managing database migrations:

Initialize the migration repository:

   flask db init

This command creates a new migration repository. It sets up a migrations directory with the necessary files for managing your migrations.

Create a migration:

   flask db migrate -m "Initial migration"

This command creates a new migration script based on the changes detected in your models. Unlike some other migration tools, Flask-Migrate automatically detects changes to your models and generates the migration script for you having to write it manually. However, it's always a good idea to review the generated migration script to ensure it reflects the intended changes.

The -m flag allows you to provide a brief description of the migration, which is helpful for tracking changes over time.

Apply the migration:

   flask db upgrade

This command applies the migration to your database, making the necessary schema changes.

It's important to review the generated migration scripts before applying them, especially in production environments. While Flask-Migrate is generally good at detecting changes, complex modifications might require manual adjustments to the migration scripts.

For more advanced usage, Flask-Migrate provides additional commands:

flask db downgrade: Reverts the last migration
flask db current: Displays the current revision of the database
flask db history: Shows the migration history

You should commit your migration files to version control so that all developers and deployment environments can maintain consistent database schemas.

To learn more about managing database migrations with Flask and Neon Postgres, check out the Managing database migrations and schema changes with Flask and Neon Postgres guide.

Scalability Considerations

Besides the above steps, as your Flask application grows, you can consider a few strategies to improve performance and scalability. Here are some best practices to keep in mind:

Connection pooling is a technique used to manage database connections efficiently. Instead of opening and closing a new connection for each database operation, a pool of reusable connections is maintained.

Neon Postgres supports connection pooling, which can significantly improve your application's performance by reducing the overhead of creating new connections.

To use connection pooling with Neon:

   # Update your DATABASE_URL to use the pooled connection string
   app.config['SQLALCHEMY_DATABASE_URI'] = 'postgresql://user:password@pooler.address:5432/database'

Refer to the Neon documentation on connection pooling for detailed instructions.

For performance optimization, consider caching frequently accessed data. Caching reduces the load on your database and speeds up response times for users.

Implement caching for frequently accessed data using Flask-Caching:

   from flask_caching import Cache

   cache = Cache()

   def create_app():
       # ... previous code ...
       cache.init_app(app, config={'CACHE_TYPE': 'simple'})

       return app

   @user_bp.route('/api/users', methods=['GET'])
   @cache.cached(timeout=60)  # Cache for 60 seconds
   def get_users_api():
       users = User.query.all()
       return jsonify([user.to_dict() for user in users])

This example uses in-memory caching ('simple'). For production, you can switch to a caching backend like Redis.

Asynchronous processing allows your application to handle time-consuming tasks without blocking the main request-response cycle. You can use Celery, a distributed task queue, to run background tasks asynchronously.

To integrate Celery with Flask, you need to install the celery package and configure it in your Flask application:

   pip install celery

   from celery import Celery

   celery = Celery(__name__)

   def create_app():
       # ... previous code ...
       celery.conf.update(app.config)

       return app

   @celery.task
   def send_email(user_id):
       user = User.query.get(user_id)
       # Send email to user

   # To call the task
   send_email.delay(user_id)

This example defines a Celery task to send an email to a user asynchronously. You can run Celery workers to process these tasks in the background.

Rate limiting helps prevent abuse of your API and ensures fair usage among clients. It's an important security measure for public APIs.

Implement rate limiting using Flask-Limiter:

   from flask_limiter import Limiter
   from flask_limiter.util import get_remote_address

   limiter = Limiter(key_func=get_remote_address)

   def create_app():
       # ... previous code ...
       limiter.init_app(app)

       return app

   @user_bp.route('/api/users', methods=['GET'])
   @limiter.limit("5 per minute")
   def get_users_api():
       users = User.query.all()
       return jsonify([user.to_dict() for user in users])

This example limits the /api/users endpoint to 5 requests per minute per IP address. You can adjust the limit based on your application's needs and resources.

Conclusion

By following these practices, you've set up a scalable Flask application with Neon Postgres, including a responsive frontend using Tailwind CSS. This structure allows for easy expansion and maintenance as your project grows.

As a next step, consider adding authentication, authorization, and error handling to your application. These features are essential for securing your application and providing a good user experience.

You should also consider testing your application to ensure its reliability and performance. Unit tests, integration tests, and end-to-end tests can help you catch bugs early and maintain code quality. Testing your application with Neon's branching feature can help you test new features in isolation before deploying them to production.

Additional Resources

Building a CRUD API with Laravel and Sanctum

Rishi Raj Jain — Fri, 04 Oct 2024 14:42:42 +0000

Laravel is a powerful PHP framework that allows developers to easily build web applications and APIs.

In this guide, we'll walk through the process of creating a CRUD (Create, Read, Update, Delete) API using Laravel, and we'll implement authentication using Laravel Sanctum.

By the end of this tutorial, you'll have a fully functional API that allows authenticated users to perform CRUD operations on a resource. We'll use a 'Task' model as our example resource and implement the necessary endpoints to manage tasks.

Prerequisites

Before we begin, ensure you have the following:

PHP 8.1 or higher installed on your system
Composer for managing PHP dependencies
A Neon account for database hosting
Basic knowledge of Laravel and RESTful API principles

Setting up the Project

Let's start by creating a new Laravel project and setting up the necessary components.

Creating a New Laravel Project

Open your terminal and run the following command to create a new Laravel project:

composer create-project laravel/laravel laravel-crud-api
cd laravel-crud-api

This will create a new Laravel project in a directory named laravel-crud-api and install all the necessary dependencies.

Setting up the Database

Update your .env file with your Neon database credentials:

DB_CONNECTION=pgsql
DB_HOST=your-neon-hostname.neon.tech
DB_PORT=5432
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

Make sure to replace your-neon-hostname, your_database_name, your_username, and your_password with your actual database credentials.

Installing Laravel Sanctum

Laravel Sanctum provides a featherweight authentication system for SPAs and simple APIs. To install it, all you need to do is use the following command:

php artisan install:api

If you get asked to run all pending migrations, type yes and press Enter. Else, run the migrations to create the necessary tables:

php artisan migrate

This will create the necessary tables for Sanctum to work.

Creating the Task Model and Migration

As mentioned earlier, for our CRUD API, we'll use a 'Task' model as our example resource. This model will have fields such as title, description, status, due date, and priority.

Let's create it along with its migration file:

php artisan make:model Task -m

Once created, open the newly created migration file in database/migrations and update it to include the necessary columns for the 'tasks' table:

public function up()
{
    Schema::create('tasks', function (Blueprint $table) {
        $table->id();
        $table->foreignId('user_id')->constrained()->onDelete('cascade');
        $table->string('title');
        $table->text('description')->nullable();
        $table->enum('status', ['pending', 'in_progress', 'completed'])->default('pending');
        $table->date('due_date')->nullable();
        $table->integer('priority')->default(1);
        $table->timestamps();
    });
}

We've defined a foreign key user_id to associate each task with a user. This allows us to implement user-specific tasks and ensure that each task belongs to a specific user. The constrained() method creates a foreign key constraint that references the id column of the users table. The onDelete('cascade') method ensures that when a user is deleted, all associated tasks are also deleted.

Run the migration to create the 'tasks' table:

php artisan migrate

After that, update the app/Models/Task.php model file to include the necessary fields in the $fillable array:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Task extends Model
{
    use HasFactory;

    protected $fillable = ['title', 'description', 'status', 'due_date', 'priority'];

    public function user()
    {
        return $this->belongsTo(User::class);
    }
}

As a reference, the fillable property specifies which fields can be mass-assigned when creating or updating a model. This helps protect against mass assignment vulnerabilities and ensures that only the specified fields can be modified.

Implementing API Authentication

Before we create our CRUD endpoints, let's set up authentication using Laravel Sanctum. This will allow users to register, log in, and access protected routes in our API.

Creating the User Registration and Login Controllers

By default, Laravel comes with a few route groups like web, api, and auth. We'll use the api group for our API routes which will be protected by Sanctum.

Start by creating a controller called AuthController to handle user registration and login using the artisan command:

php artisan make:controller Api/AuthController

Then, update the app/Http/Controllers/Api/AuthController.php file and add the necessary methods:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;

class AuthController extends Controller
{
    public function register(Request $request)
    {
        $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|string|email|max:255|unique:users',
            'password' => 'required|string|min:8|confirmed',
        ]);

        $user = User::create([
            'name' => $request->name,
            'email' => $request->email,
            'password' => Hash::make($request->password),
        ]);

        $token = $user->createToken('auth_token')->plainTextToken;

        return response()->json([
            'access_token' => $token,
            'token_type' => 'Bearer',
        ]);
    }

    public function login(Request $request)
    {
        $request->validate([
            'email' => 'required|email',
            'password' => 'required',
        ]);

        $user = User::where('email', $request->email)->first();

        if (! $user || ! Hash::check($request->password, $user->password)) {
            throw ValidationException::withMessages([
                'email' => ['The provided credentials are incorrect.'],
            ]);
        }

        $token = $user->createToken('auth_token')->plainTextToken;

        return response()->json([
            'access_token' => $token,
            'token_type' => 'Bearer',
        ]);
    }

    public function logout(Request $request)
    {
        $request->user()->currentAccessToken()->delete();

        return response()->json(['message' => 'Logged out successfully']);
    }
}

Rundown of the methods in the AuthController:

register: Handles user registration. Validates the request data, creates a new user, and returns an access token.
login: Handles user login. Validates the request data, checks the user credentials, and returns an access token.
logout: Logs out the authenticated user by deleting the current access token.

Setting up Authentication Routes

Update routes/api.php to include the authentication routes within the api route group:

<?php

use App\Http\Controllers\Api\AuthController;
use Illuminate\Support\Facades\Route;

Route::post('/register', [AuthController::class, 'register']);
Route::post('/login', [AuthController::class, 'login']);

Route::middleware('auth:sanctum')->group(function () {
    Route::post('/logout', [AuthController::class, 'logout']);
    // We'll add our task routes here later
});

The auth:sanctum middleware protects the routes by requiring a valid access token. This ensures that only authenticated users can access the protected routes.

The /register and /login routes are public and do not require authentication. Users can register and log in to obtain an access token.

Issuing API Tokens

To issue API tokens, we need to update the User model to use the HasApiTokens trait. Laravel ships with a default User model located at app/Models/User.php.

Let's update the app/Models/User.php file and add the HasApiTokens trait:

<?php

// Existing imports
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    // Add the HasApiTokens trait here
    use HasApiTokens, HasFactory, Notifiable;

    // Existing code
}

After adding the HasApiTokens trait, you can use the createToken method to generate an access token for a user. We've used this method in the AuthController to issue tokens during registration and login.

While we're here, let's also update the User model to include a relationship with the Task model:

public function tasks()
{
    return $this->hasMany(Task::class);
}

This relationship allows us to retrieve all tasks associated with a user and create new tasks for a user, simplifying the task management process.

Testing the Authentication Endpoints

To test the authentication endpoints, you can use a tool like Postman or Insomnia.

For the sake of simplicity, you can use the curl command in your terminal.

Let's start by testing the registration route and try to register a new user:

curl -X POST http://laravel-crud-api.test/api/register \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "John Doe",
        "email": "john@example.com",
        "password": "password",
        "password_confirmation": "password"
    }'

Note: Replace laravel-crud-api.test with your Laravel project URL.

The response should include an access token like this:

{
  "access_token": "1|eyJ...your_access_token_here",
  "token_type": "Bearer"
}

To log in with the registered user:

curl -X POST http://laravel-crud-api.test/api/login \
    -H 'Content-Type: application/json' \
    -d '{
        "email": "john@example.com",
        "password": "password"
    }'

This will return another access token:

{
  "access_token": "1|eyJ...your_new_access_token_here",
  "token_type": "Bearer"
}

With the access token, you can now access the protected routes. To log out, use the /logout route:

curl -X POST http://laravel-crud-api.test/api/logout \
    -H 'Authorization: Bearer <your_access_token_here>'

Replace <your_access_token_here> with the access token you received during login. This will log out the user and delete the access token and you will get a response like:

{
  "message": "Logged out successfully"
}

Implementing CRUD Operations

Now that we have authentication set up, let's create our CRUD operations for the Task model.

Creating the TaskController

Generate a new controller for handling task operations:

php artisan make:controller Api/TaskController --api

The --api flag generates a controller with the necessary methods for a RESTful API. This will create a new controller file at app/Http/Controllers/Api/TaskController.php and will include methods like index, store, show, update, and destroy.

After that, update app/Http/Controllers/Api/TaskController.php and populate those methods with the necessary logic:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Task;
use Illuminate\Http\Request;

class TaskController extends Controller
{
    public function index()
    {
        $tasks = Task::all();
        return response()->json($tasks);
    }

    public function store(Request $request)
    {
        $request->validate([
            'title' => 'required|string|max:255',
            'description' => 'nullable|string',
            'status' => 'required|in:pending,in_progress,completed',
            'due_date' => 'nullable|date',
            'priority' => 'required|integer|min:1|max:5',
        ]);

        $task = $request->user()->tasks()->create($request->all());
        return new TaskResource($task);
    }

    public function show(Task $task)
    {
        return response()->json($task);
    }

    public function update(Request $request, Task $task)
    {
        $this->authorize('update', $task);

        $validated = $request->validate([
            'title' => 'sometimes|required|string|max:255',
            'description' => 'nullable|string',
            'status' => 'sometimes|required|in:pending,in_progress,completed',
            'due_date' => 'nullable|date',
            'priority' => 'sometimes|required|integer|min:1|max:5',
        ]);

        $task->update($validated);

        return new TaskResource($task);
    }

    public function destroy(Task $task)
    {
        $task->delete();
        return response()->json(null, 204);
    }
}

Note: We'll create the TaskResource class later to transform the task model into a JSON response.

Rundown of the methods in the TaskController:

index: Fetches all tasks. Returns a JSON response with all tasks. We'll update this method to use API Resources later.
store: Creates a new task. Validates the request data, creates a new task, and returns the task as JSON.
show: Fetches a single task. Returns a JSON response with the specified task.
update: Updates a task. Validates the request data, updates the task, and returns the updated task as JSON.
destroy: Deletes a task. Deletes the specified task and returns a 204 No Content response.

Adding Task Routes

Once we have the TaskController set up, let's add the task routes to routes/api.php to include the task routes within the authenticated group:

// Include the TaskController at the top:
use App\Http\Controllers\Api\TaskController;

Route::middleware('auth:sanctum')->group(function () {
    Route::post('/logout', [AuthController::class, 'logout']);

    // Add the task routes here:
    Route::apiResource('tasks', TaskController::class);
});

The Route::apiResource method automatically generates the necessary routes for a RESTful resource. This will create routes for tasks with the appropriate HTTP verbs and route names.

You can use the php artisan route:list command to see a list of all registered routes.

Implementing API Resources

To provide a consistent and customizable way of transforming our models into JSON responses, let's use Laravel's API Resources.

A resource class represents a single model that needs to be transformed into a JSON structure. It allows you to customize the data that is returned when a model is converted to JSON rather than returning the entire model instance.

Generate a new resource for the Task model:

php artisan make:resource TaskResource

Open the app/Http/Resources/TaskResource.php file and update it as follows:

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class TaskResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'description' => $this->description,
            'status' => $this->status,
            'due_date' => $this->due_date,
            'priority' => $this->priority,
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }
}

Here, we've defined the fields that should be included in the JSON response for a task and how they should be formatted. For more complex transformations, you can customize the toArray method as needed.

Now, update the TaskController to use this resource when returning task data instead of returning the raw model:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Resources\TaskResource;
use App\Http\Controllers\Controller;
use App\Models\Task;
use Illuminate\Http\Request;

class TaskController extends Controller
{
    public function index()
    {
        $tasks = Task::all();
        // Change this line to use the TaskResource:
        return TaskResource::collection($tasks);
    }

    public function store(Request $request)
    {
        $validated = $request->validate([
            'title' => 'required|string|max:255',
            'description' => 'nullable|string',
            'status' => 'required|in:pending,in_progress,completed',
            'due_date' => 'nullable|date',
            'priority' => 'required|integer|min:1|max:5',
        ]);

        $task = $request->user()->tasks()->create($validated);

        return new TaskResource($task);
    }

    public function show(Task $task)
    {
        return new TaskResource($task);
    }

    public function update(Request $request, Task $task)
    {
        $request->validate([
            'title' => 'required|string|max:255',
            'description' => 'nullable|string',
            'status' => 'required|in:pending,in_progress,completed',
            'due_date' => 'nullable|date',
            'priority' => 'required|integer|min:1|max:5',
        ]);

        $task->update($request->all());
        return new TaskResource($task);
    }

    public function destroy(Task $task)
    {
        $task->delete();
        return response()->json(null, 204);
    }
}

Now, when you fetch tasks, create a new task, or update an existing task, the response will be formatted according to the TaskResource class.

Testing the API Endpoints

To test the new Task API, you can again use curl or a tool like Postman or Insomnia.

Let's first create a new task:

curl -X POST http://laravel-crud-api.test/api/tasks \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <your_access_token_here>' \
    -d '{
        "title": "New Task",
        "description": "Task description",
        "status": "pending",
        "due_date": "2024-12-31",
        "priority": 2
    }'

As a response, you should see the newly created task:

{
  "id": 1,
  "title": "New Task",
  "description": "Task description",
  "status": "pending",
  "due_date": "2024-12-31",
  "priority": 2,
  "created_at": "2024-07-01T00:00:00.000000Z",
  "updated_at": "2024-07-01T00:00:00.000000Z"
}

You can then fetch all tasks:

curl -X GET http://laravel-crud-api.test/api/tasks \
    -H 'Authorization: Bearer <your_access_token_here>'

This will return a list of tasks in JSON format.

Adding Pagination

To improve performance and reduce payload size, we can add pagination to the task list. Laravel provides a simple way to paginate query results using the paginate method when fetching data. That way the response will include only a subset of tasks per page instead of the entire collection which can be large depending on the number of entries in the database.

To do that, update the index method in TaskController and change the all method to paginate followed by the number of items per page:

public function index()
{
    $tasks = Task::paginate(15);
    return TaskResource::collection($tasks);
}

This pagination method will limit the number of tasks returned to 15 per page, significantly reducing the payload size for large datasets.

The response will now include additional pagination metadata such as the total number of items, the number of pages, and links to the next and previous pages, allowing for easy navigation through the entire collection of tasks.

Implementing Request Classes

Request classes allow you to encapsulate request validation logic within dedicated classes. This helps keep your controller clean and improves reusability.

To keep our controller clean and improve reusability, let's create dedicated request classes for validation for creating and updating tasks:

php artisan make:request StoreTaskRequest
php artisan make:request UpdateTaskRequest

Update app/Http/Requests/StoreTaskRequest.php to include the validation rules:

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreTaskRequest extends FormRequest
{
    public function authorize()
    {
        return true;
    }

    public function rules()
    {
        return [
            'title' => 'required|string|max:255',
            'description' => 'nullable|string',
            'status' => 'required|in:pending,in_progress,completed',
            'due_date' => 'nullable|date',
            'priority' => 'required|integer|min:1|max:5',
        ];
    }
}

Update app/Http/Requests/UpdateTaskRequest.php the same way:

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class UpdateTaskRequest extends FormRequest
{
    public function authorize()
    {
        return true;
    }

    public function rules()
    {
        return [
            'title' => 'required|string|max:255',
            'description' => 'nullable|string',
            'status' => 'required|in:pending,in_progress,completed',
            'due_date' => 'nullable|date',
            'priority' => 'required|integer|min:1|max:5',
        ];
    }
}

Now, we are ready to update the TaskController to use these request classes instead of validating the request directly in the controller methods:

// Include the request classes at the top:
use App\Http\Requests\StoreTaskRequest;
use App\Http\Requests\UpdateTaskRequest;

class TaskController extends Controller
{
    // ... other methods ...

    public function store(StoreTaskRequest $request)
    {
        $task = $request->user()->tasks()->create($request->validated());
        return new TaskResource($task);
    }

    public function update(UpdateTaskRequest $request, Task $task)
    {
        $task->update($request->validated());
        return new TaskResource($task);
    }

    // ... other methods ...
}

The end-user will still receive the same JSON response, but the validation logic is now encapsulated within the request classes. This makes the controller cleaner and easier to maintain.

Testing the API

To ensure our API works as expected, Laravel provides a powerful testing suite out of the box.

To learn more about testing in Laravel along with Neon branding, check out the Testing Laravel Applications with Neon's Database Branching.

Adding API Documentation

For better developer experience, it's important to have good API documentation.

You can use a third-party package called Scribe to generate your API documentation.

To install Scribe, run the following command:

composer require --dev knuckleswtf/scribe

Publish the configuration file:

php artisan vendor:publish --tag=scribe-config

Then update the config/scribe.php file to configure the documentation settings according to your preferences.

Generate the documentation:

php artisan scribe:generate

This will create a public/docs directory with the generated API documentation. You can access it by visiting http://laravel-crud-api.test/docs. The generated format will also include Postman collections and OpenAPI specifications.

Implementing API Versioning

As your API evolves, you might need to introduce breaking changes. API versioning allows you to do this without affecting existing clients.

To implement a simple versioning strategy, you can prefix your API routes with a version number. This way, you can maintain backward compatibility while introducing new features in future versions.

To do that, create a new directory for v1 of your API:

mkdir app/Http/Controllers/Api/V1

Move your TaskController.php to this new directory and update its namespace:

namespace App\Http\Controllers\Api\V1;

Then update your routes/api.php file to include versioning and the new namespace:

// Update the TaskController import at the top:
use App\Http\Controllers\Api\V1\TaskController;

// Update the routes to include the version prefix:
Route::prefix('v1')->group(function () {
    Route::post('/register', [AuthController::class, 'register']);
    Route::post('/login', [AuthController::class, 'login']);

    Route::middleware('auth:sanctum')->group(function () {
        Route::post('/logout', [AuthController::class, 'logout']);
        Route::apiResource('tasks', \App\Http\Controllers\Api\V1\TaskController::class);
    });
});

Now, your API endpoints will be prefixed with /api/v1. This allows you to introduce breaking changes in future versions without affecting existing clients.

Later on, you can create a new version (e.g., v2) and update the routes accordingly to maintain backward compatibility.

Implementing Caching

To improve performance, especially for frequently accessed and rarely changing data, it is a good idea to implement caching for our task list.

This can significantly reduce the response time and server load and reduce the number of database queries putting less pressure on the database.

As an example, let's implement that for the index method in TaskController:

// Include the Cache facade at the top:
use Illuminate\Support\Facades\Cache;

public function index()
{
    // Use the Cache facade to store the tasks for one hour
    $tasks = Cache::remember('tasks', 3600, function () {
        return Task::paginate(15);
    });

    return TaskResource::collection($tasks);
}

This caches the task list for one hour. Remember to clear the cache when tasks are updated, created, or deleted.

Conclusion

In this guide, we've walked through the process of building a simple CRUD API with Laravel, secured with Laravel Sanctum for authentication.

We've covered setting up the project, configuring the database with Neon, and implementing CRUD operations for a Task model. We also added essential features such as API versioning, API documentation, and caching to improve the API's performance, security, and maintainability.

By following these steps, you now have a fully functional API that allows authenticated users to manage tasks effectively. This can be used as the foundation for more complex applications and extended with additional features as needed.

As next steps you can think about adding more features to the API, such as search, filtering, sorting, and more advanced authentication and authorization mechanisms.

Additionally, it is a good idea to implement throttling to protect your API from abuse and to ensure fair usage.

Additional Resources

How to Implement Contextual Feature Flags in Angular using Unleash

Rishi Raj Jain — Fri, 02 Feb 2024 14:39:11 +0000

Feature flags are a powerful technique that allows you to toggle features on and off dynamically without redeploying your code. This can help you to deliver faster and safer web applications, as you can test new user journeys in production, perform gradual rollouts, and revert changes as required, all without triggering a redeploy.

In this tutorial, you will learn how to use custom feature flags in a Angular application that displays some magical details to the users based on their subscription (generated randomly), using Unleash. We will use the @karelics/angular-unleash-proxy-client and unleash-proxy-client packages, which provides easy integration of Unleash feature flags in an Angular application.

This article is a contribution by Rishi Raj Jain as a part of the Community Content Program. You can also suggest a topic by opening an issue, or Write for Unleash as a part of the Community Content Program.

What we’ll be using

Angular (UI)
Unleash (Feature Flags)
Tailwind CSS (Styling)

What you'll need

Docker
Node.js 18 (make sure npm works correctly)

Setting up the project

To set up, just clone the app repo and follow this tutorial to learn everything that's in it. To fork the project, run:

git clone https://github.com/rishi-raj-jain/custom-subscription-feature-flag-angular-and-unleash
cd custom-subscription-feature-flag-angular-and-unleash
npm install

Setup Unleash

Run the following commands in the terminal to fetch the docker-compose.yml for creating an Unleash instance outside of your current project directory:

git clone git@github.com:Unleash/unleash.git
cd unleash
docker compose up -d

This will start Unleash in the background. Once Unleash is running, you can access it at http://localhost:4242.

Now use the default credentials to log into the instance:

Username: admin
Password: unleash4all

Create a New Feature Flag

Create a new feature flag in your Unleash instance named subscription:

In the feature flag's dashboard, click on Add strategy in the developement environment:

Click Save to associate the pre-configured setup with the subscription feature flag.

Let's move to creating a custom context field subscription, for which we'll define a set of values that'll indicate the plans that will be supported in our app.

First, click on Configure in the navigation bar, and then click on Context fields:

You would then see a screen like below. Click on New Context Field button to create a custom field:

Now, enter the details of the custom field named subscription, such as Basic and Pro in this case.

Hit create context, and then go to your feature flag in the dashboard. Update the strategy to define the constraints to enforce subscription values.

Only users with subscription plans as Pro will see this flag as enabled.

Great. Now, let's turn on the flag in the developement environment 👇🏻

Integrating Unleash in Angular

Installation

To get started with Angular and Unleash, you need to install @karelics/angular-unleash-proxy-client and unleash-proxy-client packages.

You can run the following commands in your terminal to do this:

npm install unleash-proxy-client @karelics/angular-unleash-proxy-client

Initialize Unleash SDK

To make feature flags available to our Angular application, we will use the Unleash Context Provider. This helper will initialize the Unleash Angular SDK and provide access to feature flags throughout our application. We will do this by adding it to our src/app/app.config.ts file. Notice that we're using a refreshInterval of 1 second to get instant updates.

// File: src/app/app.config.ts

import { ApplicationConfig } from '@angular/core'
import { provideRouter } from '@angular/router'
import { routes } from './app.routes'

import { provideUnleashProxy } from '@karelics/angular-unleash-proxy-client'

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideUnleashProxy({
      refreshInterval: 1,
      appName: 'customName',
      url: 'http://localhost:4242/api/frontend',
      clientKey: 'default:development.unleash-insecure-frontend-api-token',
    }),
  ],
}

Use (Unofficial) Unleash Angular SDK to fetch the feature flag value with context

Next, we will show content based on the subscription of the user if 1. the subscription feature flag is enabled, and 2. their subscription plan is allowed in the feature flag. Let's break it into steps:

1. Subscription feature flag is enabled

To check if the subscription feature flag is enabled for a user, we'll use *featureEnabled directive.

First, import the FeatureEnabledDirective in the component.ts:

// File: src/app/app.component.ts

import { Component } from '@angular/core'
import { FeatureEnabledDirective } from '@karelics/angular-unleash-proxy-client'

@Component({
  standalone: true,
  selector: 'app-root',
  templateUrl: './app.component.html',
  imports: [FeatureEnabledDirective],
})

export class AppComponent {
  title = 'custom-subscription-feature-flag-angular-and-unleash'
}

Then, update our reactive HTML:

// File: src/app/app.component.html

<div class="contents" *featureEnabled="'subscription'; else disabledTmpl">
    <div class="mt-3">
      <span class="py-2 px-4 bg-green-100 rounded">Magical Detail</span>
    </div>
</div>
<ng-template #disabledTmpl>
    <div class="mt-3">
      <span class="py-2 px-4 bg-red-100 rounded">Fallback Content</span>
    </div>
</ng-template>

Keep in mind that we've to set the subscription context with the subscription plan to evaluate whether if their plan is allowed (enabled) to show the magical details. This all done via:

2. Update subscription as context

To pass the subscription as the context while based of a random number, we'll update our Unleash Context to include the custom context value.

Here's how we'd do that:

Updatesrc/app/app.component.ts to generate a random number:

// File: src/app/app.component.ts

export class AppComponent {
  title = 'custom-subscription-feature-flag-angular-and-unleash'
  randomNumber: number = 0

  constructor() {
    this.generateRandomNumber()
  }

  generateRandomNumber() {
    this.randomNumber = Math.random()
    if (this.randomNumber > 0.5) {
        // Do something
    }
  }
}

Set the subscription plan context:

// File: src/app/app.component.ts

import { Component } from '@angular/core'
import { FeatureEnabledDirective } from '@karelics/angular-unleash-proxy-client'

+ import { UnleashService } from '@karelics/angular-unleash-proxy-client'

@Component({
  standalone: true,
  selector: 'app-root',
  templateUrl: './app.component.html',
  imports: [FeatureEnabledDirective],
})
export class AppComponent {
  title = 'custom-subscription-feature-flag-angular-and-unleash'
  randomNumber: number = 0

+  constructor(private unleashService: UnleashService) {
    this.generateRandomNumber()
  }

  generateRandomNumber() {
    this.randomNumber = Math.random()
    if (this.randomNumber > 0.5) {
+      this.unleashService.unleash.updateContext({
+        properties: {
+          subscription: 'Pro',
+        },
+      })
    }
  }
}

Awesome, now we're able to dynamically set the subscription plan user per request, and use that with Unleash to determine if the feature flag is enabled for their use case. If so, we show them the magical details (as set in our reactive HTML src/app/app.component.html), else we present with a fallback content. Here's a preview of what we've made 👇🏻

Using Unleash in Production

To setup Unleash for production, please follow the steps below:

Self-host Unleash, or run an instance on Unleash Cloud.
Get an API key from the Unleash dashboard.
Store the API key in your Environment Variables of your hosting, which secures it and makes it accessible in your code.

Unleash has a full list of feature flag best practices that can help guide you as you architect your solution.

Conclusion

Feature flags are a powerful tool for managing features in web applications. This tutorial showed us how to use feature flags with Angular and Unleash. We have seen how to create custom context field in conjuction with how to manage feature flags in the Unleash dashboard, and how to use them in our Angular code with the @karelics/angular-unleash-proxy-client and unleash-proxy-client packages.

How to Implement Contextual Feature Flags in SvelteKit using Unleash

Rishi Raj Jain — Thu, 01 Feb 2024 14:03:49 +0000

In this tutorial, you will learn how to use custom feature flags in a SvelteKit application that displays regional content to the users based on the location they're accessing the site from, using Vercel and Unleash. You'll use the official Svelte SDK by Unleash, @unleash/proxy-client-svelte, which provides easy integration of Unleash feature flags in any Svelte application.

This article is a contribution by Rishi Raj Jain as a part of the Community Content Program. You can also suggest a topic by opening an issue, or Write for Unleash as a part of the Community Content Program.

What we’ll be using

SvelteKit (UI and API Routes)
Vercel (Edge Network)
Unleash (Feature Flags)
Tailwind CSS (Styling)

What you'll need

Docker
Node.js 18 (make sure npm works correctly)
A Vercel account

Setting up the project

To set up, just clone the app repo and follow this tutorial to learn everything that's in it. To fork the project, run:



git clone https://github.com/rishi-raj-jain/regional-content-unleash-and-sveltekit
cd regional-content-unleash-and-sveltekit
npm install

Set up Unleash

Run the following commands in the terminal to fetch the docker-compose.yml for creating an Unleash instance outside of your current project directory:



git clone git@github.com:Unleash/unleash.git
cd unleash
docker compose up -d

This will start Unleash in the background. Once Unleash is running, you can access it at http://localhost:4242.

Now use the default credentials to log into the instance:



Username: admin
Password: unleash4all

Create a New Feature Flag

Create a new feature flag in your Unleash instance named regional:

In the feature flag's dashboard, click on Add strategy in the developement environment:

Click Save to associate the pre-configured setup with the regional feature flag.

Let's move to creating a custom context field region, for which we'll define a set of values that'll indicate the languages are supported with their translation in our app.

First, click on Configure in the navigation bar and then click on Context fields:

You would then see a screen like below. Click on New Context Field button to create a custom field:

Now, enter the details of the custom field named region, such as HI and EN in this case.

Hit create context, and then go to your feature flag in the dashboard. Update the strategy to define the constraints to enforce region values.

Only users with one of these regions will see this flag as enabled.

Great. Now, let's turn on the flag in the developement environment 👇🏻

Integrating Unleash with SvelteKit

Installation

To get started with SvelteKit and Unleash, you need to install @unleash/proxy-client-svelte package as a dependency in the project repository.

You can run the following commands in your terminal to do this:



npm install -D @unleash/proxy-client-svelte

Initialize Unleash SDK

To make feature flags available to our SvelteKit application, we will create an Unleash Context component. This helper will initialize the Unleash Svelte SDK and provide access to feature flags throughout our application. We will do this by adding it to our src/routes/+page.svelte file.



// File: src/routes/+page.svelte

<script lang="ts">
    import Content from "../components/content.svelte";
    import { FlagProvider } from "@unleash/proxy-client-svelte";

    const unleashConfig = {
    // How often (in seconds) the client should poll the proxy for updates
    refreshInterval: 1,
    // The name of your application. It's only used for identifying your application
    appName: "customName",
    // Your front-end API URL or the Unleash proxy's URL (https://<proxy-url>/proxy)
    url: "http://localhost:4242/api/frontend",
    // A client-side (frontend) API token OR one of your proxy's designated client keys (previously known as proxy secrets)
    clientKey: "default:development.unleash-insecure-frontend-api-token",
  };
</script>

<FlagProvider config={unleashConfig}>
  <Content {language} />
</FlagProvider>

Use Unleash Svelte SDK to fetch the feature flag value with context

Next, we will show regional content to the user if 1. the regional feature flag is enabled, and 2. the language in their region is allowed in the feature flag. Let's break it into steps:

1. Regional feature flag is enabled

To check if the regional feature flag is enabled for a user, we'll use useFlag hook.



// File: src/components/content.svelte

<script lang="ts">
  export let language: string;

  import { useFlag } from "@unleash/proxy-client-svelte";

  const isRegionTranslated = useFlag("regional");
</script>

{#if $isRegionTranslated}
  <div class="mt-3">
    <span class="py-2 px-4 bg-green-100 rounded">
      Content in <b>{language}</b>
    </span>
  </div>
{:else}
  <div class="mt-3">
    <span class="py-2 px-4 bg-red-100 rounded"> Fallback Content </span>
  </div>
{/if}

Keep in mind that we've to set the region context with the regional to evaluate whether if their region is allowed (enabled) to be translated and shown to them. This all done via:

2. Pass language as context

To pass the language (HI OR EN) as the context while looking for regional flag, we'll update our Unleash Context Wrapper component to include the custom context value.

Here's how we'd do that:

Create a +page.server.ts that'll use the Vercel's x-vercel-ip-country header to determine the region the user is in.



import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ request }) => {
    // get the vercel IP country header containing 2 letter string for that country
    const region: string = request.headers.get('x-vercel-ip-country') || "US"
    return { region }
}

Create a map of the 2 letter country code to the language used in them:



// place files you want to import through the `$lib` alias in this folder.

// create a super collection mapping country to the language used in that region
export const countryCodeMap: Record<string, string> = {
    "IN": "HI",
    "US": "EN",
}

Pass the language as context (in unleashConfig) to the Wrapper component (FlagProvider):



<script lang="ts">
  /** @type {import('./$types').PageData} */
  export let data;

  import { countryCodeMap } from "$lib";
  import Content from "../components/content.svelte";
  import { FlagProvider } from "@unleash/proxy-client-svelte";

+  // use the dynamic country's region 2 letter code
+  const language = countryCodeMap[data.region];

  const unleashConfig = {
    // How often (in seconds) the client should poll the proxy for updates
    refreshInterval: 1,
    // The name of your application. It's only used for identifying your application
    appName: "customName",
    // Your front-end API URL or the Unleash proxy's URL (https://<proxy-url>/proxy)
    url: "http://localhost:4242/api/frontend",
    // A client-side (frontend) API token OR one of your proxy's designated client keys (previously known as proxy secrets)
    clientKey: "default:development.unleash-insecure-frontend-api-token",
+    // create custom Unleash context
+    context: { properties: { region: language } },
    // To test if the value should be returned false, uncomment below and comment above line
    // context: { properties: { region: "OP" } },
  };
</script>

<FlagProvider config={unleashConfig}>
  <Content {language} />
</FlagProvider>

Awesome, now we're able to detect the location of the user per request, get the language spoken in their region and use that to determine if the feature flag is enabled for a user. Here's a preview of what we've made 👇🏻

Using Unleash in Production

To set up Unleash for production, please follow the steps below:

Self-host Unleash, or run an instance on Unleash Cloud.
Get an API key from the Unleash dashboard.
Store the API key in your Environment Variables of your hosting, which secures it and makes it accessible in your code.

Unleash has a full list of feature flag best practices that can help guide you as you architect your solution.

Conclusion

Feature flags are a powerful tool for managing features in web applications. This tutorial showed us how to use feature flags with SvelteKit and Unleash. We have seen how to create custom context field in conjuction with how to manage feature flags in the Unleash dashboard, and how to use them in our SvelteKit code with the @unleash/proxy-client-svelte package.

How To Upload Images with Astro and Xata

Rishi Raj Jain — Sun, 21 Jan 2024 17:24:19 +0000

Hey all,

This is my first attempt at recording (and not writing!) a full-fledged tutorial 👇🏻

This tutorial is about how to handle client side image uploads with Xata and Astro. Would love any feedback, criticism or suggestions!

Forem: Rishi Raj Jain

Using Partytown with Google Tag Manager in Astro: A Step-by-Step Guide

Prerequisites

Table Of Contents

What is Partytown?

Create a new Astro application

Integrate Partytown in your Astro project

Install Partytown using Astro CLI

Configure Partytown options

Add Google Tag Manager with Partytown

Create a tracking component

Use the tracking component in your layout

Test your Astro application locally

Understanding the Performance Benefits

References

Conclusion

Comparing Text Search Strategies pg_search vs. tsvector vs. External Engines

Built-in PostgreSQL tsvector for Text Search

Example of Using tsvector

Pros of tsvector

Cons of tsvector

Extending tsvector with pg_search

Enabling pg_search on Neon

Example of Using pg_search

Why Use pg_search on Neon?

External Search Engines (e.g., Elasticsearch)

Use Cases for External Search Engines

Comparison Summary

Which Option Should You Choose?

Use built-in tsvector when:

Use pg_search on Neon when:

Consider external search engines when:

Conclusion

Building a RESTful API with ASP.NET Core, Swagger, and Neon

Prerequisites

Setting Up Your ASP.NET Core Project

Configuring the Neon Database

Creating the Entity Framework Core Models

Creating the Database Context

Running Migrations to Create the Database Schema

Building the API Endpoints

Setting Up Swagger for API Documentation

Enabling Swagger in Program.cs

Running Your Application

Testing Your API with Postman

Securing Your API with JWT Authentication (Bonus)

Generating and Using JWT Tokens

Conclusion

Creating a Multi-Tenant Application with Laravel and Neon

Prerequisites

Setting up the Project

Creating a New Laravel Project

Installing Required Packages

Setting up the Database

Implementing Multi-Tenancy

Creating the Tenant Model

Configuring Tenancy

Creating Tenant Migrations

Implementing Tenant Routes

Implementing Tenant Creation

Verifying Tenant Registration

Implementing Tenant Onboarding

Implementing Tenant Dashboard

Conclusion

Additional Resources

How to use Synthetic Data to catch more bugs with Neosync

What is Synthetic Data?

Using Synthetic data to catch more bugs

Generating diverse data to catch edge cases

Using Synthetic data for automated testing

Using Synthetic data to for performance testing

Conclusion

6 Essential Features Every Web Starter Kit Should Include

Table Of Contents

1. User Login and Account System

2. Basic Dev Tools Setup

3. Data Management Tools

4. CSS and Design Setup

5. API Setup and Tools

6. Basic Security Setup

Built-in PostgreSQL `tsvector` for Text Search

Example of Using `tsvector`

Pros of `tsvector`

Cons of `tsvector`

Extending `tsvector` with `pg_search`

Enabling `pg_search` on Neon

Example of Using `pg_search`

Why Use `pg_search` on Neon?

Use built-in `tsvector` when:

Use `pg_search` on Neon when:

Enabling Swagger in `Program.cs`