---
title: 'Expo Modules API: Get started'
sidebar_title: Get started
description: Learn about getting started with Expo modules API.
---

import { BookOpen02Icon, Grid01Icon } from '@expo/styleguide-icons';
import { BoxLink } from '~/ui/components/BoxLink';
import { Step } from '~/ui/components/Step';
import { Terminal } from '~/ui/components/Snippet';

**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.

The two recommended flows to create a new module with Expo Modules API:

- [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)

- [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)

Both of these flows are covered in the next sections.

## Adding a new module to an existing application

<Step label="1">

### Creating the local Expo module

Navigate 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:

<Terminal cmd={[`$ npx create-expo-module@latest --local`]} />

It's best to provide a meaningful module name. However, you can accept the default suggestions for the rest of the questions.

</Step>

<Step label="2">

### Using the module

If you have an **ios** directory in your project that you created using `npx expo prebuild`, you must reinstall the pods:

<Terminal cmd={[`$ pod install --project-directory=ios`]} />

> **Note:**
> If you're using a development client, you need to rebuild your development client any time you want to use new native code.

Now, import the module in your application, for example in **App.js** or **App.tsx**:

```js
import { hello } from './modules/my-module';
```

To run your app locally, run the `prebuild` command and then compile the app:

<Terminal
  cmdCopy="npx expo prebuild --clean && npx expo run:ios"
  cmd={[
    '# Re-generate the native project directories from scratch',
    '$ npx expo prebuild --clean',
    '# Run the example app on Android',
    '$ npx expo run:android',
    '# Run the example app on iOS',
    '$ npx expo run:ios',
  ]}
/>

Congratulations! You have created a local Expo module. You can now start working on it.

> **Note:**
> You can also use absolute import paths [with some configuration changes](https://expo.fyi/absolute-path-expo-modules.md).

</Step>

<Step label="3">

### Editing the module

#### Android

If you have an **android** directory in your project that you created using `npx expo prebuild`, you can open the directory in Android Studio.

You 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.

Change the `hello` method to return a different string. For example, you can change it to return "Hello world! 🌎🍎".

Rebuild the app or build a new development client and you should see your change.

#### iOS

Open 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.

Now, change the `hello` method to return a different string. For example, you can change it to return "Hello world! 🌎🍎".

Rebuild 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).

</Step>

> **Note**
>
> There are also other flows for working on an Expo module in parallel with your application.
> 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.

## Creating a new module with an example project

<Step label="1">

### Creating the Expo module

To create a new Expo module from scratch, run the `create-expo-module` script as shown below.
The 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.

<Terminal cmd={[`$ npx create-expo-module my-module`]} />

</Step>

<Step label="2">

### Running the example project

Navigate to the module directory and then open the Android and/or iOS example project by running the following commands:

<Terminal cmd={[`$ cd my-module`, `$ npm run open:android`, `$ npm run open:ios`]} />

Now, 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.

> **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.

</Step>

<Step label="3">

### Making a change

#### Android

Open 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.

#### iOS

Open 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! 🌎🍎"`.

If you added new native files, you need to reinstall the pods using `pod install --project-directory="example/ios"`.

Rebuild the app and you should see your change.

</Step>
## Next steps

Now 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.

<BoxLink
  title="Creating your first native module"
  description="Create a simple, but complete, native module to interact with Android and iOS preferences APIs."
  href="/modules/native-module-tutorial"
  Icon={BookOpen02Icon}
/>

<BoxLink
  title="Module API Reference"
  description="Outline for the Expo Module API and common patterns like sending events from native code to JavaScript."
  href="/modules/module-api"
  Icon={Grid01Icon}
/>