georgwittberger / t3-commerce-template

Headless commerce template based on T3 stack

T3 Commerce Template

This is a project template for headless commerce using T3 stack for the storefront and Medusa.js for the backend.

Getting Started

Required Software

• Node.js version 18.x (or higher)
• pnpm version 8.x (or higher)

General Preparation

1. Clone this repository.
2. Open terminal in local repository.
3. Install NPM dependencies.

pnpm install

Setting Up Medusa.js Backend

1. Open terminal in apps/backend folder.

2. Run seed script

   pnpm seed

3. Start server

   pnpm start

4. Create test customer

   curl --request POST \
     --url http://localhost:9000/store/customers \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{"first_name":"John","last_name":"Doe","email":"[email protected]","password":"supersecret","phone":"[phone]"}'

Hint: You can access Medusa.js Admin via http://localhost:9000/app and sign in with email "[email protected]" and password "supersecret".

Setting Up Next.js Storefront

1. Open terminal in apps/storefront folder.

2. Create .env file from template.

   cp .env.example .env

3. Generate secret key for Next-Auth.

   openssl rand -base64 32

4. Open .env file and insert variable with secret key.

   # .env
   NEXTAUTH_SECRET="your_secret_key"

5. Start server

   pnpm dev

Browse the Storefront

1. Visit http://localhost:3000/
2. Sign in with test customer:
   • Email: [email protected]
   • Password: supersecret

Fundamental Concepts

Storefront Based on Create T3 App

The storefront app has been set up using Create T3 App. See its documentation for more details.

Authentication Using Medusa.js

The storefront uses Next-Auth as authentication library. A custom provider is implemented to support sign in via Medusa.js API. See src/integrations/medusa/auth-provider.ts

Medusa.js session ID is stored inside the JWT managed by Next-Auth and is not exposed as part of client session data (e.g. useSession). Therefore, it can only be access on the server-side, i.e. in getServerSideProps or in API routes (including tRPC procedures). As a consequence, all queries and mutations requiring user authentication must be proxied to Medusa.js via tRPC procedures. See auth router for example: src/features/auth/server/api/auth-router.ts

Internationalization Using i18next

The storefront supports English and German. Internationalization is implemented using next-i18next. Language files with translations are located in public/locales folder.

Keep in mind that data coming from Medusa.js is not localized because there is no multi-language support yet.

Styling Using daisyUI

The storefront has some basic styling using TailwindCSS and daisyUI.

Modularization and Abstraction

To keep things simple, there are only two guidelines for modularization and abstraction in the storefront project.

1. Feature-specific code belongs into the corresponding folder inside src/features (e.g. React components dedicated to the catalog in src/features/catalog/components) while shared code goes into the top-level directories (e.g. general React components in src/components)
2. Communication with vendor-specific backend APIs is performed via service functions which create a backend-agnostic facade. These functions build the bridge between the business domain model used in React components and the underlying vendor-specific APIs (like Medusa.js model). See cart services for example: src/features/cart/services

License

MIT