Flagi w Next.js - jak je dodać i do czego są używane?

Next.js to popularna struktura oparta na React, która umożliwia tworzenie aplikacji internetowych z nowoczesnymi funkcjonalnościami, takimi jak rendering po stronie serwera (SSR), generowanie statycznych stron (SSG) oraz zaawansowane trasowanie. Dzięki tym możliwościom Next.js stało się wyborem wielu deweloperów i firm na całym świecie.

Flagi są określane jako mechanizmy umożliwiające kontrolę włączania lub wyłączania określonych funkcji w aplikacji bez konieczności zmiany kodu i jego ponownego wdrażania. Mogą być używane do eksperymentów AB, stopniowego wdrażania nowych funkcji lub dynamicznej zmiany treści strony w zależności od warunków biznesowych.

Zalety używania flag w projektach Next.js są liczne. Przede wszystkim flagi pozwalają na większą elastyczność i kontrolę nad aplikacją, co jest kluczowe, zwłaszcza przy pracy nad dużymi i skomplikowanymi systemami. Dzięki flagom możliwe jest:

1. Szybkie wdrażanie eksperymentów: Możliwość testowania różnych wersji funkcji lub treści bez konieczności zmiany kodu i ponownego wdrażania aplikacji
2. Zarządzanie funkcjami: Łatwe włączanie i wyłączanie poszczególnych funkcji, co ułatwia zespołom deweloperskim współpracę i bezpieczne wdrażanie nowych funkcji
3. Dostosowanie treści do użytkownika: Dynamiczna zmiana treści strony w zależności od preferencji użytkownika lub określonych warunków biznesowych

Implementacja flag w Next.js, zwłaszcza przy użyciu modułu @vercel/flags/next, zapewnia nowoczesny i efektywny sposób zarządzania funkcjami w aplikacji, który jest zarówno elastyczny, jak i skalowalny.

Podstawowa konfiguracja i omówienie flag Next.js

Na początek upewnij się, że masz zainstalowane Node.js oraz npm lub yarn, które są wymagane do zarządzania pakietami w projekcie Next.js. Jeśli jeszcze nie masz projektu Next.js, możesz go łatwo stworzyć za pomocą polecenia npx create-next-app@latest. Wprowadź nazwę projektu i przejdź do jego katalogu.

Następnie zainstaluj bibliotekę @vercel/flags/next. Użyj komendy npm install @vercel/flags lub yarn add @vercel/flags w zależności od używanego menedżera pakietów. Ta biblioteka pozwala zarządzać flagami funkcji bezpośrednio w kodzie Next.js.

Kolejnym krokiem jest skonfigurowanie tajnego klucza FLAGS_SECRET, który będzie używany przez SDK do odczytu nadpisanych funkcji ustawionych przez Vercel Toolbar. Aby to zrobić, wygeneruj klucz tajny za pomocą modułu crypto:

node -e "console.log(crypto.randomBytes(32).toString('base64url'))"

Uzyskany klucz powinien zostać dodany jako zmienna środowiskowa FLAGS_SECRET w pliku .env.local w katalogu głównym projektu.

Deklaracja pierwszej flagi funkcji w aplikacji Next.js

Aby zaimplementować pierwszą flagę, musimy odwołać się do funkcji unstable_flag, która jest częścią pakietu @vercel/flags. Nazwa unstable wskazuje, że funkcjonalność jest nadal w fazie eksperymentalnej. Oznacza to, że sama funkcjonalność nie jest jeszcze objęta semantycznym wersjonowaniem. Vercel nadal bada i planuje dalsze iteracje tej funkcji, z zamiarem optymalizacji i dostosowania jej do użytkowników.

1export const showHolidayBanner = flag<boolean>({
2  key: 'holiday-baner',
3  async decide() {
4    return false;
5  },
6  origin: 'https://example.com/flags/holiday-baner/',
7  description: 'Show holiday banner',
8  defaultValue: false,
9  options: [
10    { value: false, label: 'Hide' },
11    { value: true, label: 'Show' },
12  ],
13});

Oto podstawowe parametry używane przy deklarowaniu flagi funkcji:

• key (string): Klucz flagi funkcji
• decide (function): Funkcja, która rozstrzyga wartość flagi funkcji
• defaultValue (Optional) (any): Wartość domyślna, która będzie używana, jeśli funkcja `decide` zwróci `undefined` lub zgłosi błąd
• description (Optional) (string): Opis flagi funkcji.
• origin (Optional) (string): URL, gdzie można zarządzać flagą funkcji.
• options (Optional) ({ label?: string, value: any }[]): Możliwe wartości, do których może odnosić się flaga funkcji, wyświetlane w Vercel Toolbar.

Funkcja decide może pełnić różne role w zależności od logiki biznesowej, którą chcesz wdrożyć. Może zwracać wartości na podstawie zmiennych środowiskowych, używać asynchronicznych zapytań do API lub polegać na warunkach kontekstowych.

Przypadek 1: Zwracanie wartości statycznej

Prosty przypadek, gdzie funkcja decide zawsze zwraca określoną wartość, taką jak false.

1async decide() {
2  return false;
3}

Przypadek 2: Wartość na podstawie zmiennej środowiskowej

1async decide() {
2  return process.env.HOLIDAY_BANNER_ENABLED === '1';
3}

Przypadek 3: Użycie wbudowanego API JavaScript do rozstrzygania wartości flagi

1async decide() {
2  try {
3    const response = await fetch('https://api.example.com/feature-flags/holiday-baner');
4    const data = await response.json();
5    return data.enabled;
6  } catch (error) {
7    console.error('Error fetching feature flag:', error);
8    return false; 
9  }
10}

Przypadek 4: Warunki kontekstowe

1async decide() {
2  const userCountry = cookies().get('user-country').value;
3  return userCountry === 'US'; // Only US users see the Christmas banner
4}

Używanie flagi funkcji

Aby użyć flagi funkcji w projekcie Next.js, najpierw musimy ją zaimportować w odpowiednim pliku, a następnie zastosować jej wartość w kodzie.

1import { showHolidayBanner } from '../flags';
2
3export default async function Page() {
4  const isBannerVisible = await showHolidayBanner();
5
6  return (
7    <div>
8      {isBannerVisible ? (
9        <p>Holiday banner is displayed!</p>
10      ) : (
11        <p>Holiday banner is hidden.</p>
12      )}
13    </div>
14  );
15}

Przetwarzanie wstępne flag funkcji

Przetwarzanie wstępne flag to podejście, które pozwala na wcześniejsze obliczenie flag funkcji na etapie middleware. Przekazywanie tych wartości do komponentów poprawia wydajność aplikacji, zwłaszcza dla stron generowanych statycznie (SSG) i stron z dynamicznym trasowaniem.

1//flags.ts
2import { unstable_flag as flag } from '@vercel/flags/next';
3
4export const showHolidayBanner = flag<boolean>({
5  key: 'holiday-banner',
6  decide: () => false,
7  origin: 'https://example.com/flags/holiday-banner/',
8  description: 'Show holiday banner',
9  defaultValue: false,
10  options: [
11    { value: false, label: 'Hide' },
12    { value: true, label: 'Show' },
13  ],
14});
15
16export const precomputeFlags = [showHolidayBanner] as const;

W middleware obliczamy wartości flag i przekazujemy je do stron i komponentów, używając odpowiednio przepisanych URL.

1// middleware.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { unstable_precompute as precompute } from '@vercel/flags/next';
4import { precomputeFlags } from './flags';
5
6export const config = { matcher: ['/'] };
7
8export async function middleware(request: NextRequest) {
9  const code = await precompute(precomputeFlags);
10  const nextUrl = new URL(
11    `/${code}${request.nextUrl.pathname}${request.nextUrl.search}`,
12    request.url,
13  );
14  return NextResponse.rewrite(nextUrl, { request });
15}

Aby uzyskać dostęp do wartości flag obliczonych w middleware, zaimportuj niezbędne flagi i przekazany kod z URL w swoim komponencie.

1// app/[code]/page.tsx
2import { precomputeFlags, showHolidayBanner } from '../../flags';
3
4export default async function Page({ params }: { params: { code: string } }) {
5  const holidayBanner = await showHolidayBanner(params.code, precomputeFlags);
6
7  return (
8    <div>
9      {holidayBanner ? <p>Holiday banner is displayed!</p> : <p>Welcome to our website!</p>}
10    </div>
11  );
12}

Przetwarzanie wstępne flag ma kilka kluczowych zalet:

• Redukcja opóźnień ładowania: Obliczenia są wykonywane z wyprzedzeniem, eliminując konieczność wykonywania ich dynamicznie w czasie rzeczywistym.
• Zapobieganie migotaniu i przesunięciom layoutu: Wartości flag są obliczane i osadzane w URL przed załadowaniem strony, co zapobiega problemom z wyświetlaniem treści.
• Optymalizacja dla stron statycznych: Wstępnie obliczone flagi mogą być używane w scenariuszach generowania stron wstępnie obliczonych (SSG), co pozwala na zawarcie dynamicznych treści bez utraty wydajności.

Integracja flag z Vercel Toolbar

Vercel Toolbar to narzędzie deweloperskie dostarczane przez Vercel, które umożliwia zespołom łatwe zarządzanie i testowanie funkcji aplikacji w czasie rzeczywistym. Dzięki Vercel Toolbar możesz zastępować wartości flag, co pozwala na dynamiczne włączanie i wyłączanie określonych funkcji bez konieczności modyfikacji kodu aplikacji i ponownego wdrażania.

Aby korzystać z Vercel Toolbar w Next.js, należy wykonać kilka kroków:

1. Najpierw musimy zainstalować paczkę @vercel/toolbar, korzystając z npm:

npm install @vercel/toolbar

2. Następnie skonfiguruj Vercel Toolbar w pliku konfiguracyjnym Next.js (next.config.mjs):

1/** @type {import('next').NextConfig} */
2import withVercelToolbar from '@vercel/toolbar/plugins/next';
3const nextConfig = {};
4
5export default withVercelToolbar()(nextConfig);

3. Po skonfigurowaniu pakietu, musimy zaimportować Vercel Toolbar do głównego pliku layoutu naszej aplikacji, aby był on dostępny na wszystkich podstronach.

1import { VercelToolbar } from '@vercel/toolbar/next';
2
3const inter = Inter({ subsets: ['latin'] });
4
5export default function RootLayout({
6  children,
7}: Readonly<{
8  children: React.ReactNode;
9}>) {
10  return (
11    <html lang="en">
12      <body className={inter.className}>
13        {children} <VercelToolbar />
14      </body>
15    </html>
16  );
17}

Aby Vercel Toolbar mógł uzyskać informacje o flagach funkcji w twojej aplikacji, musisz dodać odpowiedni punkt końcowy API. Vercel Toolbar wykona uwierzytelnione żądanie pod ten punkt, aby pobrać definicje flag funkcji twojej aplikacji. Ważne jest, aby umieścić ten punkt na takiej ścieżce app/.well-known/vercel/flags/route.ts

1import { type ApiData, verifyAccess } from '@vercel/flags';
2import { unstable_getProviderData as getProviderData } from '@vercel/flags/next';
3import { NextResponse, type NextRequest } from 'next/server';
4import * as flags from '../../../../flags';
5
6export const runtime = 'edge';
7export const dynamic = 'force-dynamic';
8
9export async function GET(request: NextRequest) {
10  const access = await verifyAccess(request.headers.get('Authorization'));
11  if (!access) return NextResponse.json(null, { status: 401 });
12
13  return NextResponse.json<ApiData>(getProviderData(flags));
14}

Łączenie projektu z Vercel

Aby korzystać z Vercel Toolbar i zarządzać flagami funkcji, musisz opublikować swoją aplikację na Vercel. Aby to zrobić:

1. Połącz swoje repozytorium z kontem Vercel.
2. Zaloguj się do projektu, używając polecenia: vercel link
3. Uruchom aplikację: npm run dev

Korzystanie z Vercel Toolbar w aplikacji Next.js

Teraz masz dostęp do Vercel Toolbar, gdzie możesz zarządzać zdefiniowanymi flagami funkcji.

Na stronie swojej aplikacji kliknij ikonę Vercel w prawym dolnym rogu, aby otworzyć Vercel Toolbar.

W Vercel Toolbar przejdź do sekcji "Feature Flags". Tam zobaczysz dostępne flagi funkcji, ich bieżące wartości oraz szczegóły, które zdefiniowałeś. Stamtąd możesz dynamicznie włączać i wyłączać flagi, nadpisywać ich wartości i obserwować, jak zmienia się twoja aplikacja w czasie rzeczywistym.

‍

Dzięki Vercel Toolbar możesz efektywnie zarządzać funkcjami aplikacji i testować nowe funkcjonalności bez konieczności modyfikacji kodu i ponownego wdrażania projektu.

Podsumowanie

Flagi funkcji są potężnym narzędziem do zarządzania i wdrażania nowych funkcji w aplikacjach Next.js. Pozwalają na kontrolowanie, testowanie i aktywację funkcji bez konieczności modyfikowania kodu ani ponownego wdrażania aplikacji. Użycie flag funkcji w Next.js z Vercel zapewnia elastyczność i szybkość w zarządzaniu rozwijającą się aplikacją.

Używając modułu @vercel/flags/next, można deklarować flagi funkcji w kodzie Next.js. Funkcja unstable_flag pozwala na zdefiniowanie flagi, przypisując jej klucz, funkcję decyzyjną, wartość domyślną, opis i inne opcje. Funkcjonalność przetwarzania wstępnego flag pozwala na wcześniejsze obliczenie wartości flag w middleware, co poprawia wydajność aplikacji i redukuje opóźnienia ładowania. Dzięki czemu użytkownicy widzą odpowiednie treści bez konieczności oczekiwania na dynamiczne przeliczenie wartości flag.

Vercel dostarcza narzędzie deweloperskie o nazwie Vercel Toolbar, które umożliwia dynamiczne zarządzanie flagami funkcji. Dodanie endpointu API flag funkcji w Next.js pozwala Vercel Toolbar na pobranie i zarządzanie definicjami flag. Endpoint musi być uwierzytelniony i zwracać szczegółowe informacje o flagach, co pozwala na dynamiczne zarządzanie tymi funkcjami.

Korzystanie z flag funkcji w Next.js z Vercel to skuteczne podejście do zarządzania funkcjonalnościami aplikacji, umożliwiające płynne i bezpieczne wdrażanie nowych funkcjonalności bez konieczności ponownego wdrażania aplikacji. Pozwala to na szybką reakcję na zmieniające się potrzeby użytkowników i warunki rynkowe, jednocześnie zapewniając lepszą kontrolę i niezawodność aplikacji.