Getting Started

Add a .env.local file in the root of the theme app and add the following variables:

HESTIA_URL=https://hestia.staging.homeflow.co.uk
HESTIA_KEY=xxxxx
SITE=waterfords.agent.homeflow.co.uk
HOMEFLOW_DB_API_URL=https://dbapi.staging.homeflow.co.uk
HOMEFLOW_AUTHENTICATION_USER_ID=xxxxx
HOMEFLOW_AUTHENTICATION_USER_SECRET=xxxxx
HOMEFLOW_AUTHENTICATION_ADMIN_USER_ID=xxxxx
HOMEFLOW_AUTHENTICATION_ADMIN_USER_SECRET=xxxxx
IMAGES_API_URL=https://images.staging.homeflow.co.uk
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=xxxxx
LEADS_API_URL=https://leads.staging.homeflow.co.uk
USERS_API_URL=https://users.homeflow.co.uk
SEARCHES_API_URL=https://searches.homeflow.co.uk
AIRBRAKE_PROJECT_ID=519081
AIRBRAKE_PROJECT_KEY=xxxxx
BUILD_MONGODB_URI=xxxxx
MONGODB_URI=xxxxx
GOOGLE_FONTS_API_KEY=xxxxx
CAPTCHA_VERIFY_API_URL=https://www.google.com/recaptcha/api/siteverify
CAPTCHA_VERIFY_API_SECRET=xxxxx
NEXT_PUBLIC_CAPTCHA_VERIFY_API_SITE_KEY=xxxxx
NEXT_PUBLIC_ENVIRONMENT=development
DISABLE_SERVER_LOGS=true
LOG_API_REQUESTS=1
Copy

NEXTAUTH_SECRET is an arbitrary string and can be set to basically any value for local development.

NEXT_PUBLIC_ENVIRONMENT should be set to development when running locally in order for successful sign in to admin in both local production builds as well as using the dev server.

Node version

We recommend using NVM to install node versions.

You can see the Node version required in the theme's .nvmrc file, or just run nvm use in the root of the project.

Running the theme app locally

First, install dependencies:

yarn install
Copy

Run the development server (including TailwindCSS process):

yarn dev
Copy

Visit a localhost URL with a _host query param set using the agency's Homeflow V4 agency or admin URL.

For example:

Agent site: http://localhost:3000?_host=stags.agent.v4.homeflow.co.uk

Running a Production Build Locally

To run an optimised production build locally for testing purposes, use the custom dev:production script which will run a production build, compile and minify all Tailwind bundles, load ENV variables from your .env.local file and start the server:

yarn dev:production
Copy

Please be aware that you will need to stop the server and re-run this command if you make any changes, so it isn't particularly suitable for general local development.

Running yarn build instead will produce a production build but will not be an app you can run locally as it won't include ENV variables.

Type checking

Typescript is handled internally by the NextJS compiler and will fail builds if there are type errors.

Run the following command to check the whole project locally for TS errors:

yarn ts
Copy

TailwindCSS

Because we need full control over when Tailwind bundles are loaded in admin and themes, Tailwind compilation is handled by separate processes and not via the Next.js development server.

Be aware that this means hot-reloading and Hot Module Replacement may not always work predictably when working with CSS and you may need to manually refresh the browser to see some styling changes.

tailwind-merge

If you need to merge Tailwind classes and gracefully deal with conflicts, use twMerge.

This can be useful when you want a set of base classes in a component that can be optionally overridden, e.g.

className={twMerge('text-center', className)}
Copy

However, there is a performance overhead to using twMerge as it must perform conflict resolution. It is much more performant to use twJoin which will simply join the strings together. This should be used when the classes are all inside the same component and conflict resolution is not required:

className={twJoin('text-center', isActive && 'font-bold')}
Copy

You can also use a template literal for very simple examples where only a single condition is required:

className={`text-center ${isActive ? 'font-bold' : ''}`}
Copy

Container Queries vs Media Queries

In general, you should always use container queries instead of media queries when working on theme code.

Due to the requirement that page components render correctly inside the responsive admin preview, container queries must be used in place of media queries.

In Tailwind (using a plugin we have installed), this is as simple as prefixing a responsive class name with @.

So instead of md:text-xl, use @md:text-xl.

This does not apply when working on components in the admin area, only themes.

Prettier

Please use Prettier to ensure consistent formatting.

https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

For VSCode, you can enable Prettier formatting for TS and TSX files by adding the following config to your user settings JSON:

"[typescript]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
},
"[typescriptreact]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true
}
Copy

Route Handlers vs Server Actions

In general, route handlers should be used for GET requests that only retrieve data.

Server actions should (only) be used for mutating data - what would normally use POST/PUT/DELETE. This includes form/lead submissions. Server actions are not suitable for retrieving data as they use a POST request under the hood and therefore bypass caching.

Toast Notifications

Themes use React-Toastify for notifications, whereas admin uses Sonner. Sonner is much more opinionated and offers less customisation, making it less suitable for themes. Be careful when importing the toast function that you are importing it from the correct library depending on whether you are working in admin or a theme.

Shared Code

Theme apps share code through the @homeflow/v4-lib package. This should be included in each theme app directly from Bitbucket, using git tags for versioning.

e.g.

"@homeflow/v4-lib": "git+ssh://git@bitbucket.org/homeflow_developers/v4_lib.git#1.0.27",
Copy

To upgrade to a later version of the package, increment the version number after git#.

If you are working on the Lib package locally, you may want to link the theme to that local version of the package for convenience:

# inside your local `v4_lib` directory:
yarn link

# then navigate to the theme app and run:
yarn link @homeflow/v4-lib

# remember to compile changes in v4_lib
yarn dev
Copy