Add React and Next starters (#163)

Author: simon-johansson

ts/nextjs-starter/.gitignore

@@ -0,0 +1,40 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+encore.gen.go
+encore.gen.cue
+/.encore
+/encore.gen

ts/nextjs-starter/README.md

@@ -0,0 +1,103 @@
+# Next.js + Encore TS Web App Starter
+
+This is an [Encore](https://encore.dev/) + [Next.js](https://nextjs.org/) project starter. It's a great way to learn how to combine Encore's backend 
+capabilities with a modern web framework — perfect for building a web app.
+
+## Developing locally
+
+### Prerequisite: Installing Encore
+
+If this is the first time you're using Encore, you first need to install the CLI that runs the local development
+environment. Use the appropriate command for your system:
+
+- **macOS:** `brew install encoredev/tap/encore`
+- **Linux:** `curl -L https://encore.dev/install.sh | bash`
+- **Windows:** `iwr https://encore.dev/install.ps1 | iex`
+
+When you have installed Encore, run:
+
+```bash
+encore app create --example=ts/nextjs-starter
+```
+
+## Running locally
+
+Start the Encore backend:
+```bash
+encore run
+```
+
+In another terminal window, start the Next.js frontend:
+```bash
+npm run dev
+```
+
+Go to [http://localhost:3000](http://localhost:3000) in the browser to see the example frontend.
+
+You can also access Encore's [local developer dashboard](https://encore.dev/docs/observability/dev-dash) on <http://localhost:9400/> to view traces, API documentation, and more.
+
+### Generating a request client
+
+Keep the contract between the backend and frontend in sync by regenerating the request client whenever you make a change
+to an Encore endpoint.
+
+```bash
+npm run gen # Will create a new request client app/lib/client.ts
+```
+
+## Deployment
+
+For this starter, the backend will be deployed to Encore Cloud (or self-hosted) and the frontend to Vercel. The best way to go about doing that is to create a repo on GitHub and push the project there and then deploy the same codebase to both Encore Cloud and to Vercel.
+
+### Encore
+
+You can [self-host](https://encore.dev/docs/self-host/docker-build) the Encore backend or deploy it to Encore Cloud. Follow these steps to deploy your backend to a staging environment in Encore's free development cloud.
+
+1. Create a GitHub repo, commit and push the app.
+2. Open your app in the Encore [Cloud Dashboard](https://app.encore.dev).
+3. Go to your app settings and link your app to GitHub and select the repo you just created.
+4. Commit and push a change (can be anything) to GitHub to trigger a deploy.
+
+You can follow the deploy in the Cloud Dashboard. When the deploy is complete, your app will be available in the cloud.
+
+Then head over to the [Cloud Dashboard](https://app.encore.dev) to monitor your deployment and find your production URL.
+
+From there you can also connect your own AWS or GCP account to use for deployment.
+
+### Next.js on Vercel
+
+The only thing you need to do is to create a new project on Vercel and point it to your newly created GitHup repo.
+
+## CORS configuration
+
+If you are running into CORS issues when calling your Encore API from your frontend then you may need to specify which
+origins are allowed to access your API (via browsers). You do this by specifying the `global_cors` key in the `encore.app`
+file, which has the following structure:
+
+```js
+global_cors: {
+  // allow_origins_without_credentials specifies the allowed origins for requests
+  // that don't include credentials. If nil it defaults to allowing all domains
+  // (equivalent to ["*"]).
+  "allow_origins_without_credentials": [
+    "<ORIGIN-GOES-HERE>"
+  ],
+        
+  // allow_origins_with_credentials specifies the allowed origins for requests
+  // that include credentials. If a request is made from an Origin in this list
+  // Encore responds with Access-Control-Allow-Origin: <Origin>.
+  //
+  // The URLs in this list may include wildcards (e.g. "https://*.example.com"
+  // or "https://*-myapp.example.com").
+  "allow_origins_with_credentials": [
+    "<DOMAIN-GOES-HERE>"
+  ]
+}
+```
+
+More information on CORS configuration can be found here: https://encore.dev/docs/develop/cors
+
+## Learn More
+
+- [Encore Documentation](https://encore.dev/docs)
+- [Next.js Documentation](https://nextjs.org/docs)

ts/nextjs-starter/api/admin.ts

@@ -0,0 +1,57 @@
+import { api } from "encore.dev/api";
+import log from "encore.dev/log";
+import { getAuthData } from "~encore/auth";
+
+// Welcome to Encore!
+//
+// To run it this starter, execute "encore run" in your favorite shell.
+
+// ==================================================================
+
+// Endpoint that responds with a hardcoded value.
+// To call it, run in your terminal:
+//
+//	curl --header "Authorization: dummy-token" http://localhost:4000/admin
+//
+export const getDashboardData = api(
+  {
+    expose: true, // Is publicly accessible
+    auth: true, // Auth handler validation is required
+    method: "GET",
+    path: "/admin",
+  },
+  async (): Promise<DashboardData> => {
+    const userID = getAuthData()!.userID;
+    log.info("Data requested by user", { userID });
+
+    return { value: "Admin stuff" };
+  },
+);
+
+interface DashboardData {
+  value: string;
+}
+
+// ==================================================================
+
+// Encore comes with a built-in development dashboard for
+// exploring your API, viewing documentation, debugging with
+// distributed tracing, and more. Visit your API URL in the browser:
+//
+//     http://localhost:9400
+//
+
+// ==================================================================
+
+// Next steps
+//
+// 1. Deploy your application to the cloud
+//
+//     git add -A .
+//     git commit -m 'Commit message'
+//     git push encore
+//
+// 2. To continue exploring Encore with TypeScript, check out one of these topics:
+//
+//    Building a REST API:   https://encore.dev/docs/tutorials/rest-api
+//    Services and APIs:   https://encore.dev/docs/ts/primitives/services-and-apis

ts/nextjs-starter/api/auth.ts

@@ -0,0 +1,41 @@
+import { APIError, Gateway, Header, api } from "encore.dev/api";
+import { authHandler } from "encore.dev/auth";
+
+interface LoginParams {
+  email: string;
+  password: string;
+}
+
+export const login = api(
+  { expose: true, auth: false, method: "GET", path: "/login" },
+  async (params: LoginParams): Promise<{ token: string }> => {
+    // ... get the userID from database or third party service like Auth0 or Clerk ...
+    // ... create and sign a token ...
+
+    return { token: "dummy-token" };
+  }
+);
+
+interface AuthParams {
+  authorization: Header<"Authorization">;
+}
+
+// The function passed to authHandler will be called for all incoming API call that requires authentication.
+// Remove if your app does not require authentication.
+export const myAuthHandler = authHandler(
+  async (params: AuthParams): Promise<{ userID: string }> => {
+    // ... verify and decode token to get the userID ...
+    // ... get user info from database or third party service like Auth0 or Clerk ...
+
+    if (!params.authorization) {
+      throw APIError.unauthenticated("no token provided");
+    }
+    if (params.authorization !== "dummy-token") {
+      throw APIError.unauthenticated("invalid token");
+    }
+
+    return { userID: "dummy-user-id" };
+  }
+);
+
+export const gateway = new Gateway({ authHandler: myAuthHandler });

ts/nextjs-starter/api/encore.service.ts

@@ -0,0 +1,5 @@
+import { Service } from "encore.dev/service";
+
+// Encore will consider this directory and all its subdirectories as part of the "admin" service.
+// https://encore.dev/docs/ts/primitives/services
+export default new Service("api");

ts/nextjs-starter/app/admin/error.tsx

@@ -0,0 +1,21 @@
+"use client"; // Error components must be Client Components
+
+import { useEffect } from "react";
+
+export default function Error({
+  error,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    // Log the error to an error reporting service
+    console.error(error);
+  }, [error]);
+
+  if (error.message === "invalid auth param") {
+    return <p>You need to login to view this data</p>;
+  }
+
+  return <p>Something went wrong!</p>;
+}

ts/nextjs-starter/app/admin/page.tsx

@@ -0,0 +1,29 @@
+import { redirect } from "next/navigation";
+import getRequestClient from "../lib/getRequestClient";
+import { api, APIError, ErrCode } from "../lib/client";
+
+export default async function Admin() {
+  const client = await getRequestClient();
+  let response: api.DashboardData | undefined;
+  let error: APIError | undefined;
+
+  try {
+    response = await client.api.getDashboardData();
+  } catch (err) {
+    error = err as APIError;
+  }
+
+  if (error) {
+    if (error.code === ErrCode.Unauthenticated)
+      redirect("/auth/unauthenticated?from=%2Fadmin");
+    else throw error;
+  }
+
+  return (
+    <section>
+      <h1 className="text-3xl">Admin Dashboard</h1>
+      <br />
+      <p>{response?.value}</p>
+    </section>
+  );
+}

ts/nextjs-starter/app/auth/login/route.ts

@@ -0,0 +1,19 @@
+import { redirect } from "next/navigation";
+import { cookies } from "next/headers";
+import getRequestClient from "../../lib/getRequestClient";
+
+export async function POST(req: Request) {
+  const data = await req.formData();
+  const email = (data.get("email") as string) || "incognito";
+  const password = (data.get("password") as string) || "password";
+
+  try {
+    const client = await getRequestClient();
+    const response = await client.api.login({ email, password });
+    (await cookies()).set("auth-token", response.token);
+  } catch (error) {
+    console.error("Error logging in", error);
+  }
+
+  return redirect("/");
+}

ts/nextjs-starter/app/auth/logout/route.ts

@@ -0,0 +1,7 @@
+import { redirect } from "next/navigation";
+import { cookies } from "next/headers";
+
+export async function POST() {
+  (await cookies()).delete("auth-token");
+  return redirect("/");
+}

ts/nextjs-starter/app/auth/unauthenticated/page.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import { useSearchParams } from "next/navigation";
+
+export default function Unauthenticated() {
+  const searchParams = useSearchParams();
+  const fromPage = searchParams.get("from");
+
+  return (
+    <section>
+      <h1 className="text-3xl">Unauthenticated</h1>
+      <br />
+      <p>
+        You need to be logged in to view <code>{fromPage}</code>
+      </p>
+    </section>
+  );
+}