React Native Academy · Pelajaran

Mengedar Pemalam Konfigurasi sebagai Pakej npm

Pakejkan pemalam konfigurasi anda sebagai modul npm, tambahkan titik masuk app.plugin.js, terbitkan ke npm, dan pasangkannya dalam projek Expo lain untuk mengesahkan penggunaannya dengan betul.

Pelajaran 4 daripada 413 langkah

Mengedar Pemalam Konfigurasi sebagai Pakej npm ialah pelajaran React Native Academy percuma di CoddyKit. Ini ialah pelajaran 4 daripada 4. Sebanyak 3 pelajaran dalam laluan pembelajaran ini boleh dibaca sepenuhnya secara percuma — selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan praktikal dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran React Native Academy, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus React Native Academy merangkumi sejumlah 4 pelajaran.

Sebab Memakejkan Pemalam Konfigurasi

Jika anda menggunakan pemalam konfigurasi yang sama merentas beberapa projek Expo, atau ingin berkongsinya dengan komuniti React Native, memakejkannya sebagai modul npm memudahkan pengedaran. Pengguna memasangnya dengan npm install dan merujuknya mengikut nama pakej dalam app.json. Expo menemui fail app.plugin.js secara automatik pada akar pakej tanpa sebarang konfigurasi tambahan daripada pengguna.

Menstrukturkan Pakej npm

Pakej npm pemalam konfigurasi mempunyai struktur minimum: package.json, titik masuk app.plugin.js pada akar pakej (inilah fail yang dicari oleh Expo), dan secara pilihan folder src/ untuk sumber TypeScript yang disusun menjadi fail pemalam. Nama fail app.plugin.js ialah konvensyen Expo — jangan namakannya secara berbeza kerana Expo tidak dapat menemuinya secara automatik.

# 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.json

Titik Masuk app.plugin.js

Fail app.plugin.js mesti mengeksport satu fungsi sebagai eksport lalai menggunakan module.exports (CommonJS). Fungsi ini ialah pemalam konfigurasi itu sendiri — fungsi ini menerima config dan options pilihan, menggunakan pengubahsuaian, kemudian mengembalikan konfigurasi yang telah diubah suai. Jika pakej anda mempunyai langkah binaan TypeScript, app.plugin.js hanya mengeksport semula daripada folder build/ yang telah disusun.

// 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;
  });
};

Mengkonfigurasi package.json

package.json untuk pakej pemalam konfigurasi memerlukan medan standard serta beberapa konvensyen khusus Expo. Tetapkan main kepada titik masuk JS yang telah disusun (bukan app.plugin.js — fail itu berasingan). Senaraikan @expo/config-plugins dalam peerDependencies (bukan kebergantungan biasa) supaya pengguna menggunakan versi yang dipasang sendiri dan mengelakkan pemasangan pendua. Awali nama pakej dengan expo- atau gunakan nama berskop seperti @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'
  }
}

Menulis Pemalam dalam TypeScript

@expo/config-plugins mengeksport jenis TypeScript, menjadikan pemalam anda mudah ditaip dengan betul. Gunakan jenis generik ConfigPlugin bersama antara muka pilihan anda. TypeScript mengesan ralat jenis (seperti menghantar kunci manifes yang tidak sah) pada masa penyusunan, bukannya ketika prabina pengguna. Jana fail pengisytiharan (.d.ts) supaya pengguna mendapat IntelliSense ketika menghantar pilihan.

// 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;

Mengeksport Semula daripada app.plugin.js

Apabila menggunakan TypeScript, kod sumber anda disusun ke dalam build/, tetapi Expo mencari app.plugin.js pada akar projek. Cipta app.plugin.js minimum yang memerlukan keluaran yang telah disusun. Pemisahan ini memastikan sumber TypeScript kekal kemas sambil menyediakan titik masuk yang betul seperti yang dijangkakan oleh penyelesaian modul Expo. Fail ini biasanya hanya mempunyai satu atau dua baris.

// 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;

Memasang dan Menggunakan Pemalam yang Diterbitkan

Selepas diterbitkan ke npm, pengguna memasang pakej tersebut dan menambahkannya pada pemalam app.json. Expo menyelesaikan pakej mengikut nama, mencari app.plugin.js dalam folder node_modules, kemudian menjalankannya semasa prabina. Pengguna menghantar pilihan sebagai elemen kedua bagi pasangan tatasusunan pemalam. Pengalaman pembangun ini sama seperti menggunakan pemalam pihak pertama Expo sendiri.

# Install the plugin
npm install expo-plugin-my-sdk

# app.json
{
  'expo': {
    'plugins': [
      [
        'expo-plugin-my-sdk',
        {
          'apiKey': 'sk-live-abc123',
          'enableAnalytics': true
        }
      ]
    ]
  }
}

Menguji Sebelum Menerbitkan

Sebelum menerbitkan ke npm, uji pemalam anda secara setempat menggunakan npm link atau laluan file: relatif dalam package.json aplikasi ujian. Ini membolehkan anda melakukan lelaran dengan pantas tanpa menerbitkan pakej. Selepas ujian setempat, gunakan npm pack untuk mencipta arkib tar dan periksa kandungannya bagi memastikan fail yang betul disertakan. Terbitkan hanya selepas anda mengesahkan bahawa pemalam berfungsi dari awal hingga akhir.

# 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-run

Menerbitkan ke npm

Terbitkan pemalam anda dengan npm publish. Pastikan medan files dalam package.json menyertakan app.plugin.js dan build/ tetapi tidak menyertakan src/ (pengguna tidak memerlukan sumber TypeScript). Gunakan pengversian semantik: naikkan versi tampalan untuk pembaikan pepijat, versi minor untuk pilihan baharu, dan versi major apabila anda mengubah konfigurasi dengan cara yang memecahkan keserasian (contohnya, menamakan semula pilihan).

# 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 public

Menulis README yang Baik

README pemalam konfigurasi hendaklah menyertakan: arahan pemasangan, petikan app.json tepat yang menunjukkan semua pilihan yang tersedia, jadual yang mendokumenkan setiap pilihan bersama jenis, lalai dan huraian, serta senarai perubahan asli yang dibuat oleh pemalam (kebenaran yang ditambah dan kunci Info.plist yang ditetapkan). Pembangun perlu memahami perubahan yang dibuat oleh pemalam sebelum mempercayainya untuk digunakan pada projek asli mereka.

## 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 AndroidManifest

Pengversian dan Perubahan yang Memecahkan Keserasian

Pengguna pemalam konfigurasi menjalankan expo prebuild untuk menggunakan pemalam anda — mereka tidak memanggil kod anda secara terus pada masa jalan. Perubahan yang memecahkan keserasian termasuk menamakan semula pilihan, membuang pilihan, mengubah jenis pilihan atau menghasilkan keluaran asli yang berbeza sehingga entri yang telah ditambah sebelum ini terhapus. Sentiasa dokumentasikan perubahan yang memecahkan keserasian dalam CHANGELOG.md dan naikkan versi major supaya pengguna boleh mengunci versi yang selamat.

// 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 configuration

Semakan Pantas

Uji pemahaman anda tentang konsep Pembangunan Mudah Alih React Native daripada pelajaran ini.

Jawab dalam pelajaran interaktif

Ringkasan Pelajaran

Dalam pelajaran ini, anda telah mempelajari: cara menstrukturkan pakej npm untuk pemalam konfigurasi dengan app.plugin.js pada akar projek, cara menulis pemalam dalam TypeScript dan mengeksportnya semula daripada app.plugin.js, serta cara menguji secara setempat dengan npm link sebelum menerbitkan. Anda juga melihat cara mengkonfigurasi package.json dengan medan peerDependencies dan files yang betul. Seterusnya, kita akan membincangkan proses penghantaran ke App Store iOS.

Percuma untuk bermula

Pelajari JavaScript dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus: 30
Pelajaran: 120

Mula belajar secara percuma Lihat kursus penuh

Soalan Lazim

Adakah pelajaran “Mengedar Pemalam Konfigurasi sebagai Pakej npm” percuma?

Ya — sebanyak 3 pelajaran dalam laluan pembelajaran React Native Academy, termasuk “Mengedar Pemalam Konfigurasi sebagai Pakej npm”, boleh dibaca sepenuhnya secara percuma di web ini. Selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan interaktif dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Kursus React Native Academy merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Mengedar Pemalam Konfigurasi sebagai Pakej npm”?

Pakejkan pemalam konfigurasi anda sebagai modul npm, tambahkan titik masuk app.plugin.js, terbitkan ke npm, dan pasangkannya dalam projek Expo lain untuk mengesahkan penggunaannya dengan betul. Anda berlatih React Native Academy menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan React Native Academy?

Tiada pengalaman terdahulu diperlukan. Pembelajaran React Native Academy di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 4 daripada 4.

Berapa lamakah pelajaran “Mengedar Pemalam Konfigurasi sebagai Pakej npm” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran React Native Academy ini?

Ya. Setiap pelajaran React Native Academy menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

Apakah Pemalam Konfigurasi dan Bilakah Perlu Menggunakannya
Menulis Pemalam Konfigurasi Pertama Anda
Mengubah Suai AndroidManifest dan Info.plist
Mengedar Pemalam Konfigurasi sebagai Pakej npm

← Kembali ke React Native Academy