A core API client class that can be extended to support a variety of Drupal APIs, including:
To configure the monorepo for development, the following should be installed locally:
Node.js version 18 or current LTS pnpm env is recommended to manage node versions.
npm version 9.x.x
pnpm version 8.x
We recommend using npm. Run the following command to install:
npm install -g pnpm@8
There are two main workspaces in the monorepo, packages
, and examples
The api-client
package includes the base ApiClient
class which is meant to be extended by other classes that implement logic to make it easy to fetch data from Drupal.
The json-api-client
package includes the JsonApiClient
class which extends the ApiClient
, and makes it easy to fetch data from Drupal's JSON:API without deep knowledge of it.
Examples show how the packages can be used in a variety of ways.
To configure examples to use a local Drupal environment (or override other environment variables) copy .env.local.example
as .env.local
in any of the example directories.
The json-api-client-example utilizes the JsonApiClient class to demonstrate how various configuration options can be employed for retrieving data.
To contribute to this project, follow the directions below.
pnpm install
There are several scripts you can use in the monorepo.
To see all available scripts:
pnpm run
Test all projects in the monorepo that have a test script:
pnpm test
Build all packages in the monorepo:
pnpm build:packages
Start the json-api-client
example in development mode:
pnpm dev:json-api-client
Format code using Prettier:
pnpm prettier:fix
Build the examples
pnpm build:examples
Run the jso-api-client-example
pnpm serve:json-api-client-example
Run commands in a targeted project, folder, or workspace, using the
pnpm
filter flag.
For example, to build the api-client (filter by namespace):
pnpm --filter api-client build
If you need to run a command in a specific project, use the alias in the ROOT
package.json
scripts (pnpm run
to see the full list in your terminal), or
use a filter. Please do not cd
into the project directory and use npm
or
yarn
.
This project is being developed with a slight variation of the Drupal JavaScript coding standards in order to have a set of guidelines that work well with TypeScript. Since the AirBnb style guide does not officially have TypeScript support, we are using the eslint-config-airbnb-typescript package to add Typescript compatibility. We are also using TSDoc instead of JSDoc3 to standardize our doc comments.
eslint-config-airbnb-typescript
OverridesWe recommend using VSCode as your editor. You will be prompted to install the recommended extensions when you open the project in VSCode. Settings are also included in this project to format code on save using Prettier.
To generate a new changeset, run pnpm changeset
in the root of the repository.
The generated Markdown files in the .changeset
directory should be committed
to the repository.
Releases are automated using the changesets-gitlab package. To publish a new release:
canary
against main
. Do not squash commits to main as this will cause later conflicts.main
against canary
. Merge this to bring canary
up to date with the latest package versions and changesets.The example projects included in /examples
use a hosted Drupal environment by default. In cases where you need to modify data or the CMS install itself, using a local Drupal environment can be helpful.
From the root of the repository, run:
pnpm ddev:init
This will create a new Drupal instance in /drupal
, build your DDEV instance, install Drupal with Umami demo data, and configure features used by the API Client. The /drupal
directory is ignored by version control.
Drupal will be available at:
https://drupal.ddev.site
and the following API endpoints will be active:
https://drupal.ddev.site/jsonapi
https://drupal.ddev.site/router/translate-path
You will be able to interact with your DDEV instance using the ddev
command inside of the /drupal
directory. Drush will also be installed and available via ddev drush
.
From the root of the repository, run:
pnpm ddev:destroy
This will delete your DDEV instance and remove your Drupal codebase.
Ymmv, but these are the steps I followed when creating a new package that extends api-client. I don't expect us to be doing this frequently, but if that proves wrong we could create a scaffolder for this.
"@drupal-api-client/api-client": "workspace:*"
as a dependencypnpm i
at the root of the repository.README.md
in the new package directory.api-client
to the new package:src
subdirectory with:pnpm build
in the new package directory.pnpm i
at the root of the repository.pnpm dev
and pnpm build
in the new example directory.Generated using TypeDoc