xref: /expo/docs/pages/modules/get-started.mdx (revision cfa99e0f) 
1---
2title: 'Expo Modules API: Get started'
3sidebar_title: Get started
4description: Learn about getting started with Expo modules API.
5---
6
7import { BookOpen02Icon, Grid01Icon } from '@expo/styleguide-icons';
8import { BoxLink } from '~/ui/components/BoxLink';
9import { Step } from '~/ui/components/Step';
10import { Terminal } from '~/ui/components/Snippet';
11
12**There are two ways to get started with the Expo Modules API:** you can either initialize a new module from scratch or add the Expo Modules API to an existing module. This guide will walk you through creating a new module from scratch, and the [Integrating in an existing library guide](/modules/existing-library) covers the latter case.
13
14The two recommended flows to create a new module with Expo Modules API:
15
16- [Add a new module to an existing Expo application, and use it to test and develop your module.](#adding-a-new-module-to-an-existing-application)
17
18- [Create a new module in isolation with a generated example project if you want to reuse it in multiple projects or publish it to npm.](#creating-a-new-module-with-an-example-project)
19
20Both of these flows are covered in the next sections.
21
22## Adding a new module to an existing application
23
24<Step label="1">
25
26### Creating the local Expo module
27
28Navigate to your project directory (the one that contains the **package.json** file) and run the following command, which is the recommended way to create a local Expo module:
29
30<Terminal cmd={[`$ npx create-expo-module@latest --local`]} />
31
32It's best to provide a meaningful module name. However, you can accept the default suggestions for the rest of the questions.
33
34</Step>
35
36<Step label="2">
37
38### Using the module
39
40If you have an **ios** directory in your project that you created using `npx expo prebuild`, you must reinstall the pods:
41
42<Terminal cmd={[`$ pod install --project-directory=ios`]} />
43
44> **Note:**
45> If you're using a development client, you need to rebuild your development client any time you want to use new native code.
46
47Now, import the module in your application, for example in **App.js** or **App.tsx**:
48
49```js
50import { hello } from './modules/my-module';
51```
52
53To run your app locally, run the `prebuild` command and then compile the app:
54
55<Terminal
56  cmdCopy="npx expo prebuild --clean && npx expo run:ios"
57  cmd={[
58    '# Re-generate the native project directories from scratch',
59    '$ npx expo prebuild --clean',
60    '# Run the example app on Android',
61    '$ npx expo run:android',
62    '# Run the example app on iOS',
63    '$ npx expo run:ios',
64  ]}
65/>
66
67Congratulations! You have created a local Expo module. You can now start working on it.
68
69> **Note:**
70> You can also use absolute import paths [with some configuration changes](https://expo.fyi/absolute-path-expo-modules.md).
71
72</Step>
73
74<Step label="3">
75
76### Editing the module
77
78#### Android
79
80If you have an **android** directory in your project that you created using `npx expo prebuild`, you can open the directory in Android Studio.
81
82You can always just edit the files in the `modules/my-module/android/src/main/java/expo/modules/mymodule/` directory directly in your favorite text editor.
83
84Change the `hello` method to return a different string. For example, you can change it to return "Hello world! ����".
85
86Rebuild the app or build a new development client and you should see your change.
87
88#### iOS
89
90Open the files in **modules/my-module/ios/** directory in your favorite code editor to edit them. Alternatively, if you have an **ios** directory in your project that was created using `npx expo prebuild`, you can use Xcode to edit them.
91
92Now, change the `hello` method to return a different string. For example, you can change it to return "Hello world! ����".
93
94Rebuild the app or build a new development client and you should see your change. Remember you need to either run `npx expo prebuild` each time you make a native change or you reinstall the pods using `pod install --project-directory="example/ios"` (which should be way faster).
95
96</Step>
97
98> **Note**
99>
100> There are also other flows for working on an Expo module in parallel with your application.
101> For example, you can use a monorepo or publish to npm, as described in [How to use a standalone Expo module in your project](/modules/use-standalone-expo-module-in-your-project) guide.
102
103## Creating a new module with an example project
104
105<Step label="1">
106
107### Creating the Expo module
108
109To create a new Expo module from scratch, run the `create-expo-module` script as shown below.
110The script will ask you a few questions and then generate the native Expo module along with the example app for Android and iOS that uses your new module.
111
112<Terminal cmd={[`$ npx create-expo-module my-module`]} />
113
114</Step>
115
116<Step label="2">
117
118### Running the example project
119
120Navigate to the module directory and then open the Android and/or iOS example project by running the following commands:
121
122<Terminal cmd={[`$ cd my-module`, `$ npm run open:android`, `$ npm run open:ios`]} />
123
124Now, you can run the example project on your device or simulator/emulator. When the project compiles and runs, you will see "Hello world! ��" on the screen.
125
126> **Note:** If you're using Windows, you can open the example project by opening the **android** directory in Android Studio, but you cannot open the iOS project files.
127
128</Step>
129
130<Step label="3">
131
132### Making a change
133
134#### Android
135
136Open up **MyModuleModule.kt** in Android Studio (<kbd>⌘ Cmd</kbd> + <kbd>O</kbd> or <kbd>Ctrl</kbd> + <kbd>O</kbd> and search for **MyModuleModule.kt**). Change the `hello` method to return a different string. For example, you can change it to return `"Hello world! ����"`. Rebuild the app and you should see your change.
137
138#### iOS
139
140Open up **MyModuleModule.swift** in Xcode (<kbd>⌘ Cmd</kbd> + <kbd>O</kbd> or <kbd>Ctrl</kbd> + <kbd>O</kbd> and search for **MyModuleModule.swift**). Change the `hello` method to return a different string. For example, you can change it to return `"Hello world! ����"`.
141
142If you added new native files, you need to reinstall the pods using `pod install --project-directory="example/ios"`.
143
144Rebuild the app and you should see your change.
145
146</Step>
147## Next steps
148
149Now that you've learned how to initialize a module and make simple changes to it, you can continue to a tutorial or dive right into the API reference.
150
151<BoxLink
152  title="Creating your first native module"
153  description="Create a simple, but complete, native module to interact with Android and iOS preferences APIs."
154  href="/modules/native-module-tutorial"
155  Icon={BookOpen02Icon}
156/>
157
158<BoxLink
159  title="Module API Reference"
160  description="Outline for the Expo Module API and common patterns like sending events from native code to JavaScript."
161  href="/modules/module-api"
162  Icon={Grid01Icon}
163/>
164