Skip to content

Core and capability packages ​

Nacre's API is split into two parts: the core and capability packages.

  • The core is the part every Nacre project has. It's provided by @nacrejs/ios and needs no separate installation. UI, layout, text and images, animation, input, networking, local storage, file reading and writing, and web pages are all in the core.
  • A capability package is a separate npm package that provides a system capability not in the core, such as location, taking photos, or Face ID. An app has a capability only if the project installs the package for it.

The reason for the split lies with the app's users: for capabilities such as location and the camera, iOS requires the app to state, in a sentence shown to the user, why it needs them. An app that doesn't use location shouldn't be required to write that sentence, so these capabilities aren't in the core.

Available capability packages ​

PackageWhat it providesWhat to write in nacre.config.json after installingDocs
@nacrejs/keychainapplication.keychain: encrypted storage for tokens and passwordsNothingKeychain
@nacrejs/local-authenticationLAContext: Face ID and Touch ID authenticationNSFaceIDUsageDescriptionLAContext
@nacrejs/core-locationCLLocationManager, CLLocation: location while the app is in useNSLocationWhenInUseUsageDescriptionLocation
@nacrejs/user-notificationsUNUserNotificationCenter: sending local notifications, learning when a notification arrives or is tappedNothingNotifications
@nacrejs/pushapplication.remoteNotifications: registering for remote notifications, getting the device token, receiving silent pushesaps-environment in ios.entitlementsRemote notifications
@nacrejs/cameraUIImagePickerController: taking photos with the system interfaceNSCameraUsageDescriptionTaking photos
@nacrejs/photosPHPickerViewController for picking images, PHPhotoLibrary for saving images to the photo libraryNSPhotoLibraryAddUsageDescriptionPhoto library
@nacrejs/contactsCNContactPickerViewController, CNContact: letting the user pick a contactNothingContact picker
@nacrejs/app-tracking-transparencyATTrackingManager, ASIdentifierManager: tracking authorization and the advertising identifierNSUserTrackingUsageDescriptionTracking authorization and advertising identifier

The names in the third column are key names defined by iOS; the value is a sentence shown to the app's users. You write this sentence; for how, see Configuring the app: name, languages, usage descriptions. aps-environment is not a sentence but an entitlement, whose value is development or production; see Remote notifications.

Every API not listed in this table is in the core.

What it takes to use a capability package ​

Three things, using location as the example.

1. Install the package.

bash
npm install @nacrejs/core-location

Effect: the next time ios/ is generated, the app includes the location capability. Only packages listed in the project's own package.json count; if a library the project depends on uses a capability package, that doesn't count, and you must install it yourself to use it.

2. Bring in its types at the top of the entry file.

js
/// <reference types="@nacrejs/types" />
/// <reference types="@nacrejs/core-location" />

Effect: the editor and type checker recognize CLLocationManager. Without the second line, type checking reports Cannot find name 'CLLocationManager'.

3. If the package requires a usage description, write it in nacre.config.json.

json
{
  "ios": {
    "infoPlist": {
      "NSLocationWhenInUseUsageDescription": "Used to show stores near you"
    }
  }
}

Effect: when the system asks the user for location permission, the prompt shows this sentence. Packages marked "Nothing" in the third column of the table above skip this step.

Each package's documentation starts with its own version of these three steps. For the complete process from scratch, see Building your own app.

What happens if you use it without installing ​

For a capability package that isn't installed, its classes and properties don't exist in JS:

  • Reading its class name throws ReferenceError, for example new CLLocationManager().
  • Properties it adds to existing objects don't exist. Without @nacrejs/keychain installed, 'keychain' in application is false and application.keychain is undefined.
  • Type checking reports it first: the class name can't be found, or the object has no such property.

To check at run time whether a capability is present, use typeof:

js
if (typeof CLLocationManager === 'undefined') {
  console.log('This app does not have location installed');
}

Result

  • Apps without @nacrejs/core-location installed print this line; apps with it installed don't.

What happens if you install it but don't write the usage description ​

Generating ios/ reports an error and stops; the error says which package needs which key:

nacre: @nacrejs/local-authentication needs NSFaceIDUsageDescription in Info.plist: a sentence shown to the user explaining why the app needs this permission. Put it in ios.infoPlist in nacre.config.json

Write the sentence as the error says and generate again.

See also ​