Skip to content

Best practices to integrate a Drupal 8.x+ backend with a JavaScript framework frontend

License

Notifications You must be signed in to change notification settings

eworx-org/drupal-js

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Drupal decoupled backend with JS frontend

Best practices, basic steps, lists of tools and tips to help you integrate a Drupal 8.x+ backend with a JavaScript frontend.

Note: Some examples below refer only to React development and are not JS agnostic. See also the Start with React short guide.


Table of Contents

JS

Popular JS frontend frameworks

Compare JS frameworks

Online services to use when comparing frameworks (trends, popularity, usage, downloads, benchmarks etc).

Things to consider when selecting a frontend framework (in no particular order)

  • Performance
  • Stability
  • Development experience
  • Documentation and support
  • Vendors behind
  • Complexity and learning curve
  • CRUD requirements
  • Serving multiple platforms and consumers
  • Existing in-house knowledge

Tools for JS development

Note: Before using these tools try to use the built-in, bundled tools you get from each framework.

JS terminology

In order to start with JS you sould be familiar with the basic terms below. Note that some of them may refer to a specific JS framework.

  • CORS
  • Cache
  • Code splitting
  • Components
  • Composition
  • DOM
  • Data fetch
  • HMR (Hot Module Reload)
  • HOC (Higher Order Components)
  • Hook events
  • Injection
  • Invalidation
  • Isomorphic
  • PWA
  • Props
  • Routing
  • SEO
  • SSR, SSG, ISR, DSG, CSR
  • SWA
  • SideEffect
  • State
  • Web Vitals (LCP, FID, CLS)
  • a11y
  • es6/es7 etc
  • hydration
  • i18n
  • library
  • module
  • node daemon
  • package
  • virtual DOM

Learn JS frameworks basics

JS app structure

ToDo: Add some example structure here..

Sources: 1, 2, 3, 4, 5

Styling a JS app


Drupal

About Drupal decoupled solutions

Drupal slack channels

Drupal modules

Note: Modules in emphasis are the most used across the Drupal universe.

JSON API (core)

jsonapi.org, JSON API: Drupal core module documentation, Ecosystem modules for JSON:API

GraphQL

Other

Drupal Distributions

Drupal starter-kits with JS frameworks

npm packages for Drupal

Drupal common issues with decoupled

  • Displaying embedded entities on CKEditor (eg Media) inside JS components
  • Multilingual
  • Subrequets and relationships in data
  • Customizing of responses like filtering, quering and altering
  • Routing and path aliases
  • Non entities data (e.g. metatags, redirects, path aliases, image styles)
  • Workflows (Content Moderation) and revisions
  • Node preview
  • Authentication
  • Invalidate partial cache
  • Forms

Implementation matrix

An example matrix for common requirements of a decoupled Drupal backend with JS frontend.

The table show which part of the app should take care of each functionality.

For example, we could get the site logo from Drupal but we could also use a static image on the JS side as a logo.

Notice that, in some cases, there may be a combination of the two parts or a 3rd party solution (eg an external CDN for image assets).

Requirement Drupal backend JS frontend
access and permissions
authentication
basic site settings (eg logo, site name, site slogan etc)
breadcrumbs
caching
collections (views VS JSON API entity queries)
CORS
CRUD requirements
embedded HTML on CKEditor
file attachments
forms
image styles
menus
metatags
mocking data
modifying JSON response
multilingual
multisite
partial cache invalidation
path aliases
preview
redirects
relationships and field references
revisions
routing
search_api
sub-requests
third party scripts (eg gtag)
UI translations
workflows (content moderation)
xml sitemap

Framework: React

Learn React

Drupal + React

Articles for React


Framework: NextJS

Why choose NextJS

  • Better SEO. Supports SSR, SSG, ISR.
  • Built in solutions for common requirements (routing, head/metatags, images, links, font optimization, data fetching, injected scripts, i18n, AMP)
  • Built in tools (Typescript, Sass, ESLint, Webpack, env variables, preview mode, polyfills)
  • Better Development Experience (DX) (zero config, built in tools, fast refresh)
  • Based on React (can use all the React goodies)

Learn NextJS

Drupal + NextJS

NextJS popular tools

Articles for NextJS


Framework: Nuxt.js

Why choose Nuxt.js

  • Better SEO. Suppports SSR and SSG.
  • Built in solutions for common requirements (routing, head/metatags, images, links, font optimization, data fetching, injected scripts, i18n, AMP)
  • Built in tools (Typescript, Sass, ESLint, Webpack, env variables, preview mode, polyfills)
  • Better Development Experience (DX) (zero config, built in tools, fast refresh)
  • Based on Vue (can use all the Vue goodies)

Drupal + Nuxt.js = Druxt

Druxt = DRUpal + nuXT

  • druxtjs.org
  • Fully Decoupled Drupal, with Nuxt.js in the frontend.
  • Drupal JSON:API Client with Vuex caching.
  • Modular Vue.js component library system.
  • Slot and Wrapper theming system.
  • API and File proxy.

Druxt Quick-start templates


Final tips

  • Make it really "decoupled" (except if other requirements)
  • Keep it simple. Use the basic tools and extend when needed.
  • Less JS packages and less Drupal modules is prefferable.
  • Work only with NodeJS LTS versions.
  • Think in Components
  • Create enough Components
  • Modify the state directly
  • Add keys on the lists (inside JS Components)
  • Declare types, validate functions
  • Always test your Components and app
  • Dockerize your JS app
  • For security updates of npm packages prefer to update the main JS library used (eg Next, React etc) and not the several npm packages independently.
  • Drupal: Prefer Drupal modules from core (e.g. JSON API instead of GraphQL)
  • Drupal: Do not override the default Drupal field machine names on JSON
  • Drupal: prefer quering the search_api to get search results on the JS App when using 3rd party search engines like SOLR.
  • Start with the official starter kits (e.g create-react-app)

Similar resources


CONTRIBUTING

Contribution guide


LICENSE

MIT - Copyright (c) 2022 EWORX S.A.