Introduction

Let's discover PeekJS in less than 5 minutes.

Getting Started

Get started by install PeekJS in an existing project.

Requirements

• Node.js version 16.14 or above:
  • When installing Node.js, you are recommended to check all checkboxes related to dependencies.
• A existing NextJS-Projekt with following versions:
  • ReactJS: 18.x
  • Mantine: 6.x
  • NextJS: 13.x

Info

It also also possible to install peekJS in other tools like Docusaurus. Be aware that the installation progress probably varies a little bit.

Add the goodDEV npm registry to the project

to make npm aware of your custom registry, we need to create a .npmrc file in the root of the project.

/.npmrc

@gooddev:registry=https://git.gooddev.de/api/v4/projects/253/packages/npm/

Install PeekJS into a site

Install command inside your existing project-directory.

npm i @gooddev/peekjs@latest

Configuration

Because @gooddev/peekjs is a raw typescript library, uncompiled, you need to make some adjustments how webpack (the tool which packs your project files into loadable chunks for browser and nodejs).

NextJS webpack adjustment

go to next.config.js in the root of you project, and add this section:

next.config.js

const nextConfig = {
  // --- other configurations
  webpack: (config, options) => {
    config.resolve.extensions.push('.tsx');
    config.resolve.extensions.push('.ts');
    config.module.rules.push({
      test: /\.(tsx|jsx|ts|js)?$/,
      use: [
        options.defaultLoaders.babel,
        {
          loader: 'ts-loader',
          options: {
            onlyCompileBundledFiles: true,
            allowTsInNodeModules: true,
            compilerOptions: {
              sourceMap: false,
              noEmit: false
            }
          }
        }
      ],
      include: [/node_modules\/@gooddev\/peekjs/]
    });
    return config;
  }
  // --- other configurations
};

Info

As mentioned before, this part can vary, depending on underlying framework. E.g. for Docusaurus you have to create a custom plugin to override webpack config, and the config looks slight different. If you need an example, look into PeekJS docusaurus repo.

You also have to install the loader for typescript as devDependency, with:

npm i -D ts-loader

Add Context Providers for correct usage of PeekJS

Add a Wrapper around you Application, e.g. in _app.tsx or a seperate AppProvider.tsx component.

Example AppProvider.tsx:

AppProvider.tsx

import { Theme } from '@emotion/react';
import {
  BreakpointsProvider,
  PagePropertyProvider,
  RouterTransition
} from '@gooddev/peekjs';
import { Notifications } from '@mantine/notifications';
import React from 'react';
import { SWRConfig } from 'swr';

import { ScrollDirectionProvider } from '../../hooks/useScrollDirection';
import { StyleProvider } from '../../hooks/useStyle';
import { ErrorBoundary } from '../helpers/ErrorBoundary';
import { CustomFonts } from './CustomFonts';
import { MantineThemeProvider } from './MantineThemeProvider';
import { PreserveScroll } from './PreserveScroll';

type Props = {
  children?: React.ReactNode;
  theme?: Theme;
  fallback?: any;
};

export const AppProvider: React.FC<Props> = ({
                                               children,
                                               fallback,
                                               ...props
                                             }) => {
  return (
          <ErrorBoundary>
            <MantineThemeProvider>
              <Notifications position={'bottom-left'} />
              <RouterTransition />
              <PreserveScroll />
              <CustomFonts />
              <SWRConfig value={{ fallback }}>
                <ScrollDirectionProvider>
                  <BreakpointsProvider>
                    <StyleProvider>
                      <PagePropertyProvider {...props}>
                        <>{children}</>
                      </PagePropertyProvider>
                    </StyleProvider>
                  </BreakpointsProvider>
                </ScrollDirectionProvider>
              </SWRConfig>
            </MantineThemeProvider>
          </ErrorBoundary>
  );
};

AppProvider.displayName = 'AppProvider';

Please adjust specially the MantineProvider as you need for custom colors and other theme configuration. See: Official MantineProvider Documentation

info

You should now be ready to use first PeekJS (only non-Drupal) Features inside you app.

Warning (enable Drupal-Features)

From this point, only non-Drupal-Features are supported, because we did not configure the necessary information to connect to a Drupal-Backend. Lets do this in the next step.

setup .env

To inform your app to which backend it should be connected, you need some information insde of the .env file.

This is a minimal setup (dkjs example):

# environment
ENVIRONMENT=local
NEXT_PUBLIC_ENVIRONMENT=local
PROJECT_NAME=peek-nextjs
FRONTEND_ORIGIN=http://localhost:3000

# USE MOCKDATA (UNCOMMENT WHEN NEEDED)
NEXT_PUBLIC_USE_MOCKDATA=1
#NODE_TLS_REJECT_UNAUTHORIZED=0

# Authentication (Admin)
DRUPAL_CLIENT_ID=A2CoRFLvdqCu152WVwSkfQDaTuv2uJlVwJEAtpmarL4
DRUPAL_CLIENT_SECRET=thisisasecret

# Authentication (Client)
NEXT_PUBLIC_DRUPAL_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NEXT_PUBLIC_DRUPAL_CLIENT_SECRET=thisisasecret

# next-drupal configurations
DRUPAL_SITE_ID=next_js_site
DRUPAL_PREVIEW_SECRET=a79ab6f1-da80-4671-acde-d58da3f4e3e7
DRUPAL_REVALIDATE_SECRET=a79ab6f1-da80-4671-acde-d58da3f4e3e7

###### environment ######

# LOCAL
NEXT_PUBLIC_DRUPAL_BASE_URL=http://demo-backend.docker.localhost
NEXT_PUBLIC_IMAGE_DOMAIN=demo-backend.docker.localhost

# STAGE
#NEXT_PUBLIC_DRUPAL_BASE_URL=https://demo-backend.ha.stage.gooddev.de
#NEXT_PUBLIC_IMAGE_DOMAIN=demo-backend.ha.stage.gooddev.de

# PROD
#NEXT_PUBLIC_DRUPAL_BASE_URL=https://demo-backend.ha.prod.gooddev.de
#NEXT_PUBLIC_IMAGE_DOMAIN=demo-backend.ha.prod.gooddev.de

You could also copy the template .env.example and make adjustments.

Info

Be sure that the drupal-credentials are correct.

To get correct credentials consult a drupal backend developer from the goodDEV-Team.

Done

You should now be ready to use all PeekJS Features inside you app ❤️