adeusuf / nextjs-leaflet

next-leaflet

An optimized tech stack for efficiency, an all-in-one solution to quickly build modern web apps.

Powered by

• NextJS
• Pocketbase

Features

• Realtime Database
• Authentication
• File Storage
• Localization

Includes

• Tailwind
• Gravatar
• Heroicons
• HeadlessUI

Getting Started

Development

Dependencies

• Install docker and docker compose.

  • Windows: Docker Desktop
  • Linux: Guide from Digital Ocean
  • Ubuntu >20.04: Guide from Thijmen Heuvelink

Development

Ensure that you've cloned the repository and are on the correct path.

Start

docker compose up

The stack is now accessible on your preferred browser at http://localhost:3000, the pocketbase interface can be found at http://localhost:3000/pb/_/

Stop

To stop the stack from running simply execute the CTRL + C shortcut.

Production

Preparation

1. Create a .env file:

   • Locate the .env.sample file in your project directory.
   • Duplicate or copy the contents of this file.
   • Rename the duplicate or copied file to .env.

2. Configure the environment variable:

   • Open the .env file in a text editor.
   • Locate the line that defines the PRODUCTION variable.
   • Set the value of PRODUCTION to "true" (include the quotes).

Production

Start

Unlike in the development steps we now add the -d flag which makes the service run in the background.

docker compose up -d

The stack is now accessible on your preferred browser at http://localhost:3000 or on a differently defined port as stated in the .env file, the pocketbase interface can be found at http://localhost:3000/pb/_/

Stop

docker compose down

Fundamentals

Install Node Packages

Install

docker compose exec next npm i -D <package>

Remove

docker compose exec next npm r <package>

NPM Modules

Next Navigation API

Instead of using next/navigation you should opt for the helper at @helpers/navigation, this is a replacement required by next-intl it offers the same functionality.

Link useRouter Redirect usePathname

Accessing Pocketbase

Pocketbase has a client executable, below is an example that outputs all available commands. You can learn more on how to use it here.

docker compose exec pocketbase pocketbase --help

CLI

Schema Snapshots

Executing the following will generate a schema snapshot in src/backend/migrations, note that this process does not save any collection data.

docker compose exec pocketbase pocketbase migrate collections

Pocketbase Migrations

Gravatar

This helper allows you to easily obtain an image URL from an email address using Gravatar API.

Implementation

1. Import the helper into your route.

   import gravatar from '@/helpers/gravatar'

2. Obtain the avatar from gravatar.

   const avatar = gravatar('[e-mail]')

   This will return a URL from the Gravatar API which is an image. Here's an example result: https://www.gravatar.com/avatar/372...ba9?s=200&r=g&d=identicon

3. (Optional) You can also choose the avatar style.

   const avatar = gravatar('[e-mail]', 'identicon')    

   You can choose between the following avatar types:

   identicon monsterid wavatar retro robohash

   The default icon style is identicon

Example

Here's an example of how you can use the Gravatar helper in your code. It is recommended to add a fallback image in case Gravatar doesn't return anything or to display while Gravatar is still loading.

import gravatar from '@/helpers/gravatar'

export default function Page() {

    const [avatar, setAvatar] = useState<string>('<fallback_url>')

    // This'll run once when the page loads. 
    useEffect(() => {
        setAvatar(gravatar(user.email))
    }, [])

    return (
        <>
            <Image src={avatar} alt="" />
        </>
    )
}

Helpers Avatars

Extras

Continuous Integration

Preparation

The workflow has been set up to connect to any VPS via SSH as defined in the Repository Secrets.

1. Install docker and docker compose on your VPS.

   • Windows: Docker Desktop
   • Linux: Guide from Digital Ocean
   • Ubuntu >20.04: Guide from Thijmen Heuvelink

2. Setup a Runner on GitHub

   1. Create a new Runner

      • Navigate to Settings > Actions > Runners

        To set up a new self-hosted runner, follow the instructions provided by GitHub to configure the runner to listen for jobs. It is advisable to install it as a service.

   2. Define environment variables

      • Navigate and create new secrets in Settings > Secrets and variables > Actions

        Name	Expects	Description
        SSH_KEY	Private Key	Generated private ssh-key which will beused to access the VPS.
        SSH_HOST	IP Address	The address of your VPS that runs theGitHub Actions Runner.
        SSH_USER	Username	System user which should be utilized for deployments.
        SSH_PORT	Port Number	The port that will be used to connectwith the VPS, default is 22.
        APP_ENV	Environment	Contents of the .env file withadjusted values for deployment.

Activation

Define the branch in .github/deploy.yml and modify it from being disabled to an existing branch. Any modifications made to that particular branch will automatically trigger the Action, deploying your stack to your VPS.