enonic-types

TypeScript types for Enonic XP

This library contains TypeScript types for Enonic XP. You can get an introduction to usage in this recording from the Enonic Meetup 13 Apr 2021:

Installing enonic-types

Install enonic-types from npm by running:

npm i --save-dev enonic-types

Add support to use typed import updating your tsconfig.json file (or src/main/resources/tsconfig.server.json if you are using the webpack-starter) with the "types" field:

{
  "compilerOptions": {
    "types": ["node", "enonic-types"],
    "rootDirs": [
      "./src/main/resources",
      "./.xp-codegen"
    ],
  },
  "include": [
    "./.xp-codegen/**/*",
    "./src/main/resources/**/*"
  ],
  "exclude": ["./build/*"]
}

And you're ready to start coding!

Code generation

We recommend using this library together with the xp-codegen-plugin Gradle plugin. xp-codegen-plugin will create TypeScript interfaces for your content-types. Those interfaces will be very useful together with this library.

Example

We have an Enonic service that returns an article by id.

import { Article } from "../../site/content-types"; // 1
import * as contentLib from "/lib/xp/content"; // 2

export function get(req: XP.Request): XP.Response { // 3
  const content = contentLib.get<Article>({ 
    key: req.params.id!
  });

  if (content !== null) { // 4
    const article: Article = content.data;

    return {
      status: 200,
      body: article
    }
  } else {
    return { 
      status: 404
    };
  }
}

1. We import an interface Article { ... } generated by xp-codegen-plugin.
2. If you added enonic-types to the types in your tsconfig.json or tsconfig.server.json (see above), TypeScript should now be able to add types to all the standard XP-libraries.
3. We use XP.Request and XP.Response to control the shape of our controller.
4. content is of the type Content<Article> | null, so we have to do a null check before proceeding.

Using vanilla JavaScript

If your project is using vanilla JavaScript, you can still get the benefit of code completion when using libraries. This is even better if you are using JsDoc to add types to your code.

All you have to do is the following:

1. Configure ./tsconfig.json as described above
2. Add a file: ./src/main/resources/types.ts with the following content:

   type LibMap = import('enonic-types/libs').EnonicLibraryMap;
   
   declare const require: <K extends keyof LibMap | string = string>(
     path: K
   ) => K extends keyof LibMap ? LibMap[K] : unknown;
   
   declare const resolve: (
     path: string
   ) => import('enonic-types/thymeleaf').ResourceKey;
   
   declare const app: {
     name: string;
     version: string;
     config: { [key: string]: string };
   };
   
   declare const log: {
     info: (...args: unknown[]) => void;
     warning: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
   };
   
   declare const __: {
     newBean: (bean: string) => unknown;
     toNativeObject: <A = unknown>(beanResult: A) => A;
   };
   

Using __non_webpack_require__

If your project is using __non_webpack_require__, you should update your types.ts file to add type support to it.

If you add (or replace the existing) __non_webpack_require__() function with the following code, it will automatically look up the correct interfaces for Enonic XP-libraries.

type LibMap = import("enonic-types/libs").EnonicLibraryMap;

declare const __non_webpack_require__: <K extends keyof LibMap | string = string>(path: K) => K extends keyof LibMap
  ? LibMap[K]
  : any;

Supported libraries

• AdminLibrary
• AuditLogLibrary
• AuthLibrary
• CacheLibrary
• ClusterLibrary
• CommonLibrary
• ContentLibrary
• ContextLibrary
• ControllerLibrary
• CristinLibrary
• CronLibrary
• EncodingLibrary
• EventLibrary
• ExplorerLibrary
• ExportLibrary
• FreeMarkerLibrary
• GraphQLLibrary
• GridLibrary
• GuillotineLibrary
• HttpLibrary
• I18nLibrary
• IOLibrary
• MailLibrary
• MenuLibrary
• MustacheLibrary
• NodeLibrary
• NotificationsLibrary
• PortalLibrary
• QRLibrary
• ProjectLibrary
• React4XPLibrary
• RecaptchaLibrary
• RepoLibrary
• RouterLibrary
• SchedulerLibrary
• SentryLibrary
• SessionLibrary
• SqlLibrary
• TaskLibrary
• TestingLibrary
• ThymeleafLibrary
• TurboLibrary
• ValueLibrary
• VhostLibrary
• WebsocketLibrary
• XsltLibrary

Changelog

0.5.0

New global maps are used for registering shapes of Content Types, as well as the shape of Site.config and Content.x.

Note If you are using xp-codegen-plugin@2.0.0 all the global declarations mentioned below are automatically generated for you based on the xml-files in your project! :tada:

ContentType map

The type system can now look up the content types when using contentLib.query() with the contentTypes parameter set.

For the type system to know about the shape of a content type, we first need to register it. This is done in a global declaration.

export type Article = import("./article").Article
export type Employee = import("./employee").Employee

declare global {
  namespace XP {
    interface ContentTypes {
      "com.mysite:article": Article;
      "com.mysite:employee": Employee;
    }
  }
}

This declaration only needs to be done once in your code base, and every XP.ContentTypes will now be merged to one interface.