This is a starter template for building web applications using Next.js, created by CA&ES.
- Next.js: A React framework for building server-rendered applications.
- TypeScript: Strongly typed programming language that builds on JavaScript.
- Dev Container: Docker-based development environment for consistent setups.
- Tailwind CSS: Utility-first CSS framework for rapid UI development.
- PostgreSQL: Relational database management system.
- Prisma: Next-generation ORM for Node.js and TypeScript.
- AuthJS (Next-Auth): Authentication solution for Next.js applications.
- ESLint: Tool for identifying and reporting on patterns in JavaScript.
- Prettier: Code formatter for maintaining consistent code style.
- tRPC: End-to-end typesafe APIs for Next.js applications.
- Still need to setup devcontainer plugins
- People should run
npx auth secretto generate a secret for auth.js for new projects - This is monorepo so everything after this assumes you are in the web directory
This project uses AuthJS for authentication. The configuration is located in src/server/auth/config.ts.
You can set up authentication providers such as Microsoft Entra ID and UC Davis CAS. Make sure to configure the environment variables in your .env file.
The login page src/app/(public)/login/page.tsx is used for the sign-in process. You can customize this page as needed or make it auto login if you want.
Any page under src/app/(protected) will require authentication to access.
Roles are up to you but if you want to add them to the session take a look at the AuthJS documentation.
The initial migration and prisma schema seen here are from AuthJS Prisma Adapter.
These tables hold the user login info and other session info. We can extend them if desired.
- create a new app registration in entra
- set the redirect URI to http://localhost:3000/api/auth/callback/microsoft-entra-id
- add some branding if desired and set publisher domain to ucdavis.edu
- create a client secret and save it
- clientID is the application (client) ID
- add the
AUTH_UCD_ENTRA*env vars to your.env.localfile - the issuer is
https://login.microsoftonline.com/a8046f64-66c0-4f00-9046-c8daf92ff62b/v2.0where that ID is our UCD Azure AD tenant ID
CAS is not working right now.
We use PostgreSQL and Prisma to query it. The DATABASE_URL env var is autogenerated based on your dev container folder name. If you want to use a different database, you can set the DATABASE_URL in your .env.local file.
To create a new migration, run:
npm run db:generateThis will generate a new migration file in the prisma/migrations directory based on the changes in your Prisma schema since the last migration (compared against your db).
To apply the migration to your database, run:
npm run db:migratetRPC is used for type-safe API calls.
You have a few options for making queries depending on your needs:
See / for an example of just a simple server-only query. This is useful for data that doesn't need to be reactive or updated on the client side. No API call is actually made over the wire, the query is executed directly on the server.
See /client for examples of just doing regular client-side queries w/ react-query.
See /prefetch for examples of prefetching data on the server and then using it in a client component. These are useful for data that you want to load on the server but then use in a client component without making another API call.
Routes are in src/server/api/routes/. You can create new files here to define your API endpoints.
Each route is given the db and user session as context.
Inside src/server/trpc/trpc.ts we've created publicProcedure and protectedProcedure to help with route protection. You can create your own procedures as needed, ex: adminProcedure or editorProcedure. Routes are created as a specific type of procedure and will thus run whatever checks you have defined for that procedure.
Alternately (or additionally), if you include the user roles in the auth session you can just check the session in your route handler.
We use Pino for logging. The logger is configured in src/lib/logger.ts.
The logger is set up to log to both stdout and Elasticsearch in production. In development, it logs to stdout with pretty printing.
If you want to log to Elasticsearch, set the LOG_ELASTIC_URL environment variable in your .env.local file.
You can use the logger in your code like this:
import { logger } from '@/lib/logger';
logger.info('Hello, world!');
logger.error('An error occurred', { error: new Error('Something went wrong') });==============================
You'll need to have Docker and a Dev Container extension setup to run inside a dev container. For VS Code, read this guide for setup details.
Clone the repository to your local machine:
git clone https://github.com/ucdavis/app-template/ my-app
cd my-appThis project is a "monorepo" and the web application is located in the web directory. You can navigate to it with:
cd webThe following instructions assume you are in the web directory and will be about getting the web application up and running.
Setup auth.js secret so you can login:
npx auth secretMigrate (setup) the database:
npm run db:migrateSetup the Prisma client (also whenever you change the Prisma schema):
npx prisma generateBy default, all pages under src/app/(protected) require authentication, and this includes the homepage.
You can change this by either just putting things in the src/app/(public) directory instead, but otherwise you'll need to setup auth.
[TBD: Add more details on auth setup here, like how to configure providers, etc.]
You can set up your secrets in the .env.local file. Copy the .env.example file to .env.local and fill in the required values.
cp .env.example .env.localTo run the application in development mode, use:
npm run devThis will start the Next.js development server on http://localhost:3000.
Going there will show the homepage, which is a protected page that requires authentication.
If you want to just look at a public page (which works without auth or db being setup), you can go to http://localhost:3000/public.