Config Plugins als npm-pakketten distribueren
Verpak uw config-plugin als een npm-module, voeg een app.plugin.js-entrypoint toe, publiceer naar npm en installeer de module in een ander Expo-project om te controleren of deze correct wordt toegepast.
Config Plugins als npm-pakketten distribueren is een gratis React Native Academy-les op CoddyKit. Dit is les 4 van 4. Je kunt 3 lessen uit dit leerpad gratis volledig lezen — daarna ontgrendelt CoddyKit PRO alle lessen, plus praktische oefeningen met een ingebouwde code-editor en een AI-tutor die 24/7 beschikbaar is. Deze les maakt deel uit van het leertraject React Native Academy. Je voortgang wordt gesynchroniseerd op het web en in de CoddyKit-app. De cursus React Native Academy bevat in totaal 4 lessen.
Waarom je een configuratieplug-in verpakt
Als je dezelfde configuratieplug-in in meerdere Expo-projecten gebruikt of deze met de React Native-community wilt delen, maakt het verpakken ervan als npm-module distributie eenvoudig. Gebruikers installeren de module met npm install en verwijzen er in app.json naar met de pakketnaam. Expo vindt het bestand app.plugin.js automatisch in de hoofdmap van het pakket, zonder extra configuratie door de gebruiker.
De structuur van het npm-pakket
Een npm-pakket voor een configuratieplug-in heeft een minimale structuur: een package.json, een toegangspunt app.plugin.js in de hoofdmap van het pakket (dit is het bestand waar Expo naar zoekt) en optioneel een map src/ voor TypeScript-broncode die naar het plug-inbestand wordt gecompileerd. De bestandsnaam app.plugin.js is de conventie van Expo — geef het bestand geen andere naam, anders kan Expo het niet automatisch vinden.
# Package structure
expo-plugin-my-sdk/
app.plugin.js <- Expo auto-discovers this
index.js <- optional JS API exports
package.json
README.md
# Or with TypeScript build:
expo-plugin-my-sdk/
src/
withMyPlugin.ts
index.ts
build/
withMyPlugin.js <- compiled output
app.plugin.js <- re-exports from build/
package.jsonHet toegangspunt app.plugin.js
Het bestand app.plugin.js moet als standaardexport één functie exporteren met module.exports (CommonJS). Deze functie is de configuratieplug-in zelf: de functie ontvangt config en optioneel options, past wijzigingen toe en retourneert de gewijzigde configuratie. Als je pakket een TypeScript-bouwstap heeft, exporteert app.plugin.js eenvoudig opnieuw uit de gecompileerde map build/.
// app.plugin.js (root of the npm package)
// Simple single-file plugin:
const { withInfoPlist } = require('@expo/config-plugins');
/** @type {import('@expo/config-plugins').ConfigPlugin<{ apiKey?: string }>} */
module.exports = function withMySDK(config, options = {}) {
if (!options.apiKey) {
throw new Error('[expo-plugin-my-sdk] apiKey option is required.');
}
return withInfoPlist(config, (iosConfig) => {
iosConfig.modResults['MySDKApiKey'] = options.apiKey;
return iosConfig;
});
};package.json configureren
De package.json voor een configuratieplug-in heeft de standaardvelden plus enkele Expo-specifieke conventies nodig. Stel main in op je gecompileerde JS-toegangspunt (niet op app.plugin.js — dat staat daar los van). Vermeld @expo/config-plugins in peerDependencies (niet in gewone afhankelijkheden), zodat gebruikers hun eigen geïnstalleerde versie gebruiken en dubbele installaties voorkomen. Begin de pakketnaam met expo- of gebruik een naamruimte zoals @yourorg/expo-plugin-name.
{
'name': 'expo-plugin-my-sdk',
'version': '1.0.0',
'description': 'Expo config plugin for MySDK',
'main': 'build/index.js',
'files': ['build', 'app.plugin.js'],
'scripts': {
'build': 'tsc',
'prepare': 'npm run build'
},
'peerDependencies': {
'@expo/config-plugins': '>=7.0.0',
'expo': '>=50.0.0'
},
'devDependencies': {
'@expo/config-plugins': '^7.0.0',
'typescript': '^5.0.0'
}
}De plug-in schrijven in TypeScript
@expo/config-plugins exporteert TypeScript-typen, waardoor je je plug-in eenvoudig correct kunt typeren. Gebruik het generieke type ConfigPlugin met je interface voor opties. TypeScript onderschept typefouten (zoals het doorgeven van een ongeldige manifestsleutel) tijdens het compileren in plaats van tijdens de prebuild van de gebruiker. Genereer declaratiebestanden (.d.ts), zodat gebruikers IntelliSense krijgen wanneer ze opties doorgeven.
// src/withMySDK.ts
import { ConfigPlugin, withInfoPlist, withAndroidManifest } from '@expo/config-plugins';
interface MySDKOptions {
apiKey: string;
enableAnalytics?: boolean;
}
const withMySDK: ConfigPlugin<MySDKOptions> = (config, options) => {
if (!options.apiKey) {
throw new Error('[expo-plugin-my-sdk] apiKey is required');
}
config = withInfoPlist(config, (c) => {
c.modResults['MySDKApiKey'] = options.apiKey;
c.modResults['MySDKAnalytics'] = options.enableAnalytics ?? true;
return c;
});
return config;
};
export default withMySDK;Opnieuw exporteren vanuit app.plugin.js
Bij gebruik van TypeScript wordt je broncode gecompileerd naar build/, maar Expo zoekt in de hoofdmap naar app.plugin.js. Maak een minimaal app.plugin.js dat de gecompileerde uitvoer vereist. Door deze scheiding blijft de TypeScript-broncode overzichtelijk en krijgt Expo het juiste toegangspunt dat de moduleoplossing verwacht. Het bestand bevat doorgaans slechts één of twee regels.
// app.plugin.js (root)
// Re-export the compiled TypeScript plugin
module.exports = require('./build/withMySDK').default;
// Or with named export:
// const { withMySDK } = require('./build/index');
// module.exports = withMySDK;De gepubliceerde plug-in installeren en gebruiken
Nadat het pakket naar npm is gepubliceerd, installeren gebruikers het pakket en voegen ze het toe aan de plug-ins in app.json. Expo zoekt het pakket op naam, vindt app.plugin.js in de map node_modules en voert het uit tijdens prebuild. De gebruiker geeft opties door als het tweede element van de tupel van de plug-inarray. Dit biedt precies dezelfde ontwikkelaarservaring als de eigen plug-ins van Expo.
# Install the plugin
npm install expo-plugin-my-sdk
# app.json
{
'expo': {
'plugins': [
[
'expo-plugin-my-sdk',
{
'apiKey': 'sk-live-abc123',
'enableAnalytics': true
}
]
]
}
}Testen vóór publicatie
Test je plug-in lokaal voordat je deze naar npm publiceert, met npm link of een relatief file:-pad in de package.json van de testapp. Zo kun je snel itereren zonder te publiceren. Gebruik na het lokaal testen npm pack om een tarball te maken en de inhoud ervan te inspecteren, zodat je controleert of de juiste bestanden zijn opgenomen. Publiceer de plug-in pas nadat je hebt bevestigd dat deze van begin tot eind werkt.
# Method 1: npm link (symlink)
cd expo-plugin-my-sdk
npm link
cd ../my-test-app
npm link expo-plugin-my-sdk
npx expo prebuild --clean
# Method 2: file path in package.json
{
'dependencies': {
'expo-plugin-my-sdk': 'file:../expo-plugin-my-sdk'
}
}
# Inspect pack output before publishing
npm pack --dry-runPubliceren naar npm
Publiceer je plug-in met npm publish. Controleer of het veld files in package.json app.plugin.js en build/ bevat, maar src/ uitsluit (gebruikers hebben de TypeScript-broncode niet nodig). Gebruik semantische versies: verhoog de patchversie voor foutoplossingen, de minorversie voor nieuwe opties en de majorversie wanneer je de configuratie op een niet-compatibele manier wijzigt (bijvoorbeeld door een optie te hernoemen).
# Login to npm
npm login
# Verify what will be published
npm pack --dry-run
# Should include:
# app.plugin.js
# build/withMySDK.js
# build/withMySDK.d.ts
# package.json
# README.md
# Publish
npm publish
# For scoped packages (public)
npm publish --access publicEen goede README schrijven
Een README voor een configuratieplug-in moet het volgende bevatten: de installatieopdracht, het exacte app.json-fragment met alle beschikbare opties, een tabel waarin elke optie met het type, de standaardwaarde en de beschrijving wordt gedocumenteerd, en de lijst met native wijzigingen die de plug-in aanbrengt (welke machtigingen deze toevoegt en welke Info.plist-sleutels deze instelt). Ontwikkelaars moeten begrijpen wat de plug-in wijzigt voordat ze deze aan hun native project toevertrouwen.
## Installation
npm install expo-plugin-my-sdk
## Setup (app.json)
[
'expo-plugin-my-sdk',
{
'apiKey': 'your-api-key',
'enableAnalytics': true
}
]
## Options
| Option | Type | Required | Default | Description |
|-------------------|---------|----------|---------|----------------------|
| apiKey | string | yes | - | Your MySDK API key |
| enableAnalytics | boolean | no | true | Enable analytics |
## Native Changes
- iOS: Adds `MySDKApiKey` to Info.plist
- Android: Adds `<meta-data android:name="com.mysdk.API_KEY" />` to AndroidManifestVersiebeheer en niet-compatibele wijzigingen
Gebruikers van configuratieplug-ins voeren expo prebuild uit om je plug-in toe te passen — ze roepen je code niet rechtstreeks tijdens runtime aan. Niet-compatibele wijzigingen zijn onder andere: opties hernoemen, opties verwijderen, het type van een optie wijzigen of andere native uitvoer genereren waardoor een eerder toegevoegde vermelding wordt verwijderd. Documenteer niet-compatibele wijzigingen altijd in een CHANGELOG.md en verhoog de majorversie, zodat gebruikers een veilige versie kunnen vastzetten.
// CHANGELOG.md example
## [2.0.0] - Breaking Changes
- BREAKING: Renamed `apiKey` option to `publishableKey` to match SDK terminology
- BREAKING: Removed `enableAnalytics` option (now always enabled)
- Added `merchantId` option for Apple Pay support
## [1.2.0]
- Added `enableAnalytics` option
## [1.1.0]
- Added Android support (previously iOS only)
## [1.0.0]
- Initial release: iOS Info.plist configurationKorte controle
Test je begrip van de concepten voor mobiele ontwikkeling met React Native uit deze les.
Samenvatting van de les
In deze les heb je geleerd hoe je een npm-pakket voor een configuratieplug-in structureert met app.plugin.js in de hoofdmap, hoe je de plug-in in TypeScript schrijft en opnieuw exporteert vanuit app.plugin.js en hoe je lokaal test met npm link voordat je publiceert. Je hebt ook gezien hoe je package.json configureert met de juiste velden voor peerDependencies en files. Hierna behandelen we het indieningsproces voor de iOS App Store.
Leer JavaScript met een AI-tutor — gratis
Schrijf echte code en voer die uit in je browser, krijg direct hulp van een AI-tutor die 24/7 beschikbaar is en ga verder waar je gebleven bent op het web of in de app.
- Cursussen
- 30
- Lessen
- 120
Veelgestelde vragen
Is de les “Config Plugins als npm-pakketten distribueren” gratis?
Ja — je kunt hier op het web alle 3 lessen van het leerpad React Native Academy, waaronder “Config Plugins als npm-pakketten distribueren”, gratis volledig lezen. Daarna ontgrendelt CoddyKit PRO alle lessen, plus interactieve oefeningen met een ingebouwde code-editor en een AI-tutor die 24/7 beschikbaar is. De cursus React Native Academy bevat in totaal 4 lessen.
Wat leer ik in “Config Plugins als npm-pakketten distribueren”?
Verpak uw config-plugin als een npm-module, voeg een app.plugin.js-entrypoint toe, publiceer naar npm en installeer de module in een ander Expo-project om te controleren of deze correct wordt toegepa… Je oefent met React Native Academy door code rechtstreeks in de browser uit te voeren. Een AI-begeleider die 24/7 beschikbaar is beantwoordt je vragen terwijl je de les doorwerkt.
Heb ik ervaring nodig om met React Native Academy te beginnen?
Ervaring vooraf is niet nodig. React Native Academy op CoddyKit is opgebouwd voor beginners tot gevorderden, zodat je hier of bij het begin kunt starten en in je eigen tempo kunt leren. Dit is les 4 van 4.
Hoe lang duurt de les “Config Plugins als npm-pakketten distribueren”?
De meeste lessen van CoddyKit duren ongeveer 5–10 minuten. Elke les is kort en interactief, zodat je gestaag vooruitgaat en op het web en in de app precies verdergaat waar je was gebleven.
Kan ik code schrijven en uitvoeren in deze les over React Native Academy?
Ja. Elke les over React Native Academy bevat een ingebouwde code-editor, zodat je rechtstreeks in je browser echte code kunt schrijven en uitvoeren en direct feedback van AI krijgt — lokale installatie is niet nodig.
Alle lessen in deze cursus
- Wat zijn Config Plugins en wanneer gebruikt u ze
- Uw eerste Config Plugin schrijven
- AndroidManifest en Info.plist aanpassen
- Config Plugins als npm-pakketten distribueren