• Expo (React Native) for the mobile frontend
• NestJS for the backend API
• Supabase for authentication and database
• Stack (full-stack integration)

Let’s explore how these technologies work together to create a seamless development experience while delivering performant applications.

The Problem: Cross-Platform Development Challenges

Building applications that work across different platforms often involves complex tradeoffs:

1. Native app performance vs. development speed
2. Backend security and structure vs. flexibility
3. Authentication implementation and management
4. Database setup, maintenance, and scaling

The ENSS Stack addresses these challenges by combining best-in-class technologies that work seamlessly together.

Why Choose the ENSS Stack?

1. Expo (React Native)

Expo simplifies React Native development with:

• Fast iteration through hot reloading
• Simple setup without the need for Xcode or Android Studio
• Managed workflow handling complex native modules
• Over-the-air updates for quick bug fixes
• TypeScript support for better type safety

2. NestJS Backend

NestJS provides:

• A structured, Angular-inspired architecture
• Built-in TypeScript support
• Dependency injection system for better testing
• Comprehensive documentation and community support
• Modular design for scalable applications

3. Supabase

Supabase offers:

• PostgreSQL database with real-time capabilities
• Built-in authentication and user management
• Row-level security for fine-grained access control
• Storage solution for files and media
• Open-source infrastructure with cloud and self-hosting options

4. Full-Stack Integration

The integration between these technologies:

• Type-safety across the entire application
• Consistent development experience
• Shared authentication context
• Simplified deployment and maintenance

Getting Started with the ENSS Stack

Let’s walk through setting up a basic application using the ENSS stack.

Prerequisites

Before we begin, ensure you have:

• Node.js 18+ and npm installed
• A Supabase account (free tier available)
• Basic familiarity with TypeScript, React, and API concepts

Project Structure

The ENSS stack template follows this structure:

enss-stack/
├── mobile/           # Expo React Native mobile app
├── backend/          # NestJS backend API

Step 1: Setting Up Supabase

1. Create a new Supabase project at supabase.com
2. Enable Google authentication in the Auth settings
3. Create a “profiles” table in the database with the following schema:

create table
  public.profiles (
    id uuid not null references auth.users on delete cascade,
    updated_at timestamp with time zone null,
    username text null,
    full_name text null,
    avatar_url text null,
    constraint profiles_pkey primary key (id)
  ) tablespace pg_default;

4. Set up Row Level Security policies for the profiles table:

alter table public.profiles enable row level security;

create policy "Users can view their own profile" on profiles
  for select using (auth.uid() = id);

create policy "Users can update their own profile" on profiles
  for update using (auth.uid() = id);

Step 2: Setting Up the NestJS Backend

1. Clone the ENSS stack template:

git clone https://github.com/yourusername/enss-stack.git
cd enss-stack/backend

2. Install dependencies:

npm install

3. Configure environment variables by copying and updating the .env.example file:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL="your-supabase-url"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your-supabase-anon-key"
SUPABASE_SERVICE_ROLE_KEY="your-supabase-service-role-key" 
SUPABASE_CONNECTION_STRING="your-supabase-connection-string"

# Server Configuration
PORT=3000

4. Start the development server:

npm run start:dev

The NestJS backend includes several key components:

Supabase Service

This service initializes and manages the connection to Supabase:

@Injectable()
export class SupabaseService implements OnModuleInit {
  private adminClient: SupabaseClient;

  onModuleInit() {
    // Initialize the admin client on module initialization
    this.adminClient = this.createAdminClient();
  }

  createAdminClient(): SupabaseClient {
    const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
    const supabaseServiceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY;

    if (!supabaseUrl || !supabaseServiceRoleKey) {
      throw new Error(
        'Missing Supabase URL or service role key. Please check your environment variables.',
      );
    }

    return createClient(supabaseUrl, supabaseServiceRoleKey, {
      auth: {
        autoRefreshToken: false,
        persistSession: false,
      },
    });
  }

  getAdminClient(): SupabaseClient {
    return this.adminClient;
  }
}

Auth Guard

The SupabaseAuthGuard protects routes that require authentication:

@Injectable()
export class SupabaseAuthGuard implements CanActivate {
  constructor(private readonly supabaseService: SupabaseService) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const authHeader = request.headers.authorization;

    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      throw new UnauthorizedException('Missing or invalid authorization token');
    }

    const token = authHeader.split(' ')[1];
    const adminClient = this.supabaseService.getAdminClient();

    try {
      // Use Supabase admin client to verify the JWT without RLS restrictions
      const { data, error } = await adminClient.auth.getUser(token);

      if (error || !data.user) {
        throw new UnauthorizedException('Invalid token or user not found');
      }

      // Attach the user to the request object for later use
      request.user = data.user;
      return true;
    } catch (error) {
      throw new UnauthorizedException('Authentication failed');
    }
  }
}

User Decorator

A custom decorator makes it easy to access the authenticated user:

export const User = createParamDecorator(
  (data: string | undefined, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user = request.user;
    
    // If a property key is provided, return that specific property
    return data ? user?.[data] : user;
  },
);

Auth Controller

Protected routes can be created with minimal code:

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @UseGuards(SupabaseAuthGuard)
  @Get('profile')
  async getProfile(@User() user) {
    return {
      user,
      message: 'You have successfully accessed a protected route',
    };
  }

  @UseGuards(SupabaseAuthGuard)
  @Get('user-data')
  async getUserData(@User('id') userId: string) {
    // Get user data from Supabase database
    const userData = await this.authService.getUserData(userId);
    return { userData };
  }

  @Get('public')
  getPublicMessage() {
    return {
      message: 'This is a public endpoint that anyone can access',
    };
  }
}

Step 3: Setting Up the Expo Mobile App

1. Navigate to the mobile app directory:

cd ../mobile

1. Install dependencies:

npm install

1. Configure environment variables by copying and updating the .env.example file:

# Supabase Configuration
EXPO_PUBLIC_SUPABASE_URL="your-supabase-url"
EXPO_PUBLIC_SUPABASE_ANON_KEY="your-supabase-anon-key"

# API Configuration
EXPO_PUBLIC_API_BASE_URL="http://localhost:3000"

1. Start the Expo development server:

npm start

The mobile app includes several key components:

Supabase Client

The supabase client is configured with AsyncStorage for token persistence:

import "react-native-url-polyfill/auto";
import AsyncStorage from "@react-native-async-storage/async-storage";
import { createClient } from "@supabase/supabase-js";
import { Database } from "../types/supabase";

const supabaseUrl = process.env.EXPO_PUBLIC_SUPABASE_URL!;
const supabaseAnonKey = process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY!;

export const supabase = createClient<Database>(supabaseUrl, supabaseAnonKey, {
    auth: {
        storage: AsyncStorage,
        autoRefreshToken: true,
        persistSession: true,
        detectSessionInUrl: true,
    },
});

Auth Context

A React context manages authentication state across the app:

const AuthContext = createContext<AuthContextType | undefined>(undefined);

export const AuthProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
    const [user, setUser] = useState<User | null>(null);
    const [session, setSession] = useState<Session | null>(null);
    const [isLoading, setIsLoading] = useState(true);
    const [error, setError] = useState<AuthError | null>(null);

    // Authentication state management and methods...
    return (
        <AuthContext.Provider value={{ 
            user, 
            session, 
            isLoading, 
            error, 
            signInWithGoogle, 
            signOut, 
            clearError 
        }}>
            {children}
        </AuthContext.Provider>
    );
};

export const useAuth = () => {
    const context = useContext(AuthContext);
    if (context === undefined) {
        throw new Error('useAuth must be used within an AuthProvider');
    }
    return context;
};

Login Screen

The login screen uses the auth context for Google authentication:

export default function LoginScreen() {
    const { user, isLoading, signInWithGoogle, error, clearError } = useAuth();

    // Handle authentication errors
    useEffect(() => {
        if (error) {
            Alert.alert(
                'Authentication Error',
                error.message,
                [{ text: 'OK', onPress: clearError }]
            );
        }
    }, [error, clearError]);

    // If the user is already authenticated, redirect to the main app
    if (user && !isLoading) {
        return <Redirect href="/(tabs)" />;
    }

    return (
        <View style={styles.container}>
            <Text style={styles.title}>ENSS Stack</Text>
            <Text style={styles.subtitle}>Expo • NestJS • Supabase • Stack</Text>

            <Button
                title="Sign in with Google"
                onPress={signInWithGoogle}
                loading={isLoading}
                fullWidth
                style={styles.button}
            />

            {error && (
                <Text style={styles.errorText}>{error.message}</Text>
            )}
        </View>
    );
}

Private Routes

The app uses Expo Router for navigation with protected routes:

// In _layout.tsx for the tabs section
import { Redirect, Stack } from 'expo-router';
import { useAuth } from '@/contexts/AuthContext';

export default function TabsLayout() {
    const { user, isLoading } = useAuth();

    // If the user isn't authenticated, redirect to the login screen
    if (!user && !isLoading) {
        return <Redirect href="/login" />;
    }
    
    return (
        <Tabs>
            <Tabs.Screen name="index" options={{ title: 'Home' }} />
            <Tabs.Screen name="profile" options={{ title: 'Profile' }} />
        </Tabs>
    );
}

Security Considerations

The ENSS stack implements several security best practices:

1. JWT Token-based Authentication: Secure, stateless authentication using Supabase JWTs
2. Backend Validation: NestJS guards verify tokens before allowing access to protected endpoints
3. Row-Level Security: Supabase RLS ensures users can only access their own data
4. Service Role Key Protection: Backend uses Supabase service role key securely without exposing it to clients
5. HTTPS Communication: All API calls should use HTTPS in production

Performance Optimizations

For optimal performance:

1. API Response Caching: Implement caching strategies for frequently-accessed data
2. Lazy Loading: Use dynamic imports and React Suspense for code-splitting
3. Optimized Database Queries: Ensure database queries are properly indexed
4. Image Optimization: Use Expo’s image optimization tools for mobile assets

Deployment Considerations

For deploying your ENSS stack application:

1. Backend (NestJS):

• Deploy to a Node.js-friendly platform like Vercel, Render, or AWS Elastic Beanstalk
• Set up proper environment variables for production
• Configure CORS to only allow requests from your mobile app

2. Mobile App (Expo):

• Use EAS Build for creating native binaries
• Configure over-the-air updates for quick fixes
• Set up different environment configurations for staging and production

Extending the ENSS Stack

The base template can be extended with:

1. State Management: Add Redux or Zustand for complex state
2. UI Components: Integrate UI libraries like NativeBase or React Native Paper
3. Testing: Set up Jest and React Testing Library for comprehensive tests
4. CI/CD: Implement GitHub Actions or CircleCI for continuous integration

Conclusion

The ENSS stack provides a robust foundation for building cross-platform applications with modern technologies. By combining Expo, NestJS, and Supabase, you get the benefits of:

• TypeScript throughout the entire stack
• Secure authentication and data storage
• Fast development iterations
• Cross-platform compatibility
• Scalable architecture

Whether you’re building a personal project or a production application, the ENSS stack offers a developer-friendly experience without sacrificing performance or security.

Resources

Repository: https://github.com/season179/enss-stack-starter

Then I hit a wall. Not just a minor hiccup, but a build-stopping error message that left me scratching my head:

./utils/supabase/server.ts
Error:   × You're importing a component that needs "next/headers". That only works in a Server Component which is not supported in the pages/ directory. Read more: https://nextjs.org/docs/app/building-
  │ your-application/rendering/server-components
  │ 
  │ 
   ╭─[/Users/season/my-next-app/utils/supabase/server.ts:2:1]
 1 │ import { createServerClient } from "@supabase/ssr";
 2 │ import { cookies } from "next/headers";
   · ───────────────────────────────────────
 3 │ 
 4 │ export const createClient = async () => {
 5 │   const cookieStore = await cookies();
   ╰────

My first reaction was confusion. I was using features from the app directory elsewhere, so why was this utility file (utils/supabase/server.ts), which used cookies from next/headers to interact with Supabase on the server-side, suddenly complaining about the pages/ directory?

After digging through my codebase and tracing where this createClient function was being called, the slightly embarrassing truth emerged: I had accidentally created a hybrid Next.js setup. My Supabase server utility, designed with app directory capabilities in mind (like accessing cookies via next/headers), was being imported and used by a part of my application still living under the rules of the pages directory (perhaps an API route in pages/api/ or an older page component).

The error message was explicit: next/headers only works in Server Components, which are not supported in the pages/ directory. My unintentional hybrid setup wasn't just messy; it was causing direct conflicts between the two paradigms. This wasn't a strategic choice; it was a byproduct of my evolving understanding (or lack thereof) and "vibe coding" my way through integrating different pieces. It became crystal clear that this approach wasn't sustainable. I needed to actually understand the difference and make a conscious decision.

This error became the catalyst for some focused research. What exactly was the difference between pages and app, and why did mixing them lead to errors like this? My conclusion after digging in? It was time to clean house and commit fully to the app directory.

The Accidental Hybrid Trap (Illustrated by an Error)

My project had somehow ended up with:

• Server-side utilities (utils/supabase/server.ts) written using app directory APIs like next/headers.
• Code operating within the pages directory context (like API routes or older page components) trying to use those utilities.

The problem wasn’t just having two folders; it was the incompatible assumptions each paradigm makes:

• API Mismatches: The app directory provides server-only APIs like cookies() from next/headers. The pages directory has its own ways of handling server-side logic (like getServerSideProps) and doesn't recognize these newer APIs. Trying to use one within the context of the other leads directly to errors like the one I encountered.
• Routing and Rendering Confusion: Which system was responsible for rendering the page or handling the API request that ultimately called my utility? The error showed the pages directory context was active where an app directory feature was expected.
• Debugging Nightmare: The error message pointed the way, but it highlighted how easily these conflicts can arise when the boundary between app and pages isn't clearly managed.

(The rest of the blog post can continue as previously drafted, discussing the pages directory, the app directory, and the reasons for choosing app, but now grounded in this specific, concrete error.)

How does that feel? It makes the “bug” much more specific and directly ties the technical limitation (next/headers in pages) to the decision-making process.

Understanding the Old Guard: The pages Directory

My research started with what I was more familiar with (or thought I was):

• Structure: File-based routing where pages/about.js becomes /about. Simple.
• Data Fetching: Relies on getServerSideProps, getStaticProps, etc. – distinct functions exported from the page file.
• Layouts: Primarily handled globally via _app.js and _document.js. Nested or route-specific layouts require workarounds like the getLayout pattern, which I hadn't consistently used.

The pages directory is proven and stable, but its limitations, especially around nested layouts and its client-side-first rendering approach, felt less aligned with modern patterns.

Embracing the New: The app Directory

This was the area I’d dabbled in without full comprehension. The key differentiators became much clearer:

• React Server Components (RSCs): The game-changer. Components run on the server by default, minimizing client-side JS. Interactivity is opt-in with 'use client'. This fundamentally changes how you think about data fetching and rendering.
• Native Nested Layouts: Solves the layout problem elegantly. layout.js files create persistent UI shells for specific route segments, preserving state and improving navigation performance naturally.
• Integrated Data Fetching: Often simpler, using async/await directly within Server Components.
• Built-in UI States: loading.js and error.js provide file-based conventions for handling loading and error states within segments.
• Server Actions: Streamline form submissions and mutations without manually creating API endpoints.

Why the app Directory Became the Clear Choice

Once I understood the two systems properly, the benefits of standardizing on the app directory, especially after my debugging ordeal, were compelling:

1. Eliminating Accidental Complexity: The most immediate win. A single, unified system for routing, layouts, and data fetching removes the ambiguity and potential for conflicts that plagued my hybrid setup. No more guessing which paradigm is in control.
2. Modern Features & Performance: RSCs, native nested layouts, streaming, and Server Actions offer powerful tools for building faster, more efficient applications with a better developer experience. Why leave these on the table?
3. Improved Developer Ergonomics: The built-in conventions (loading.js, error.js, layouts) reduce boilerplate and make structuring the application more intuitive (once learned).
4. Future-Proofing: The app directory is the clear focus of Next.js development. Committing to it aligns the project with the framework's future direction.

Moving Forward: Intentional Structure

My accidental foray into the hybrid pages/app world was a valuable, if frustrating, lesson. It highlighted the importance of understanding the foundational choices in a framework, rather than just "vibe coding" through them. The complexity and the bug it caused were direct results of not having a clear, intentional structure.

I’m now refactoring my project to use the app directory exclusively. The research born from fixing my bug gave me the clarity I needed. While there's a learning curve associated with the app directory's concepts (especially RSCs), the payoff in terms of reduced complexity, enhanced features, and future alignment feels undeniable. If you find yourself juggling both directories, especially unintentionally, I highly recommend taking the time to understand the differences and consider making a clean switch – your future self (and your debugger) might thank you.