Diego Freniche

Senior Developer Advocate

In a [past post](https://mongodb.prakticum-team.ru/developer/quickstart/document-swift-powered-frameworks-using-docc/) of this series, we showed how easy it was to generate documentation for our frameworks and libraries using DocC and the benefits of doing it. We also saw the different content we can add, like articles, how-tos, and references for our functions, classes, and structs.

But once generated, you end up with an archived DocC folder that is not _that_ easy to share. You can compress it, email it, put it somewhere in the cloud so it can be downloaded, but this is not what we want. We want:

* Automatic (and continuous) generation of our DocC documentation bundle.
* Automatic (and continuous) posting of that documentation to the web, so it can be read online. 

## What’s in a DocC bundle?

A `.doccarchive` archive is, like many other things in macOS, a folder. [Clone the repository we created with our documentation](https://github.com/mongodb-developer/realm-binary-tree-docc) and look inside `BinaryTree.doccarchive` from a terminal. 

```bash
git clone https://github.com/mongodb-developer/realm-binary-tree-docc 
cd BinaryTree.doccarchive
```

You’ll see:

```
..
├── css
│   ├── …
│   └── tutorials-overview.7d1da3df.css
├── data
│   ├── documentation
│   │   ├── binarytree
│   │   │   ├── …
│   │   │   └── treetraversable-implementations.json
│   └── tutorials
│       ├── binarytree
│       │   ├── …
│       │   └── traversingtrees.json
│       └── toc.json
├── downloads
├── favicon.ico
├── favicon.svg
├── images
│   ├── …
│   └── tree.png
├── img
│   ├── …
│   └── modified-icon.5d49bcfe.svg
├── index
│   ├── availability.index
│   ├── data.mdb
│   ├── lock.mdb
│   └── navigator.index
├── index.html
├── js
│   ├── chunk-2d0d3105.459bf725.js
│   ├ …
│   └── tutorials-overview.db178ab9.js
├── metadata.json
├── theme-settings.json
└── videos
```

This is a single-page web application. Sadly, we can’t just open `index.html` and expect it to render correctly. As [Apple explains in the documentation](https://developer.apple.com/documentation/Xcode/distributing-documentation-to-external-developers), for this to work, it has to be served from a proper web server, with a few [rewrite rules](https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html#rewriterule) added: 

> To host a documentation archive on your website, do the following:
> 
> 1. Copy the documentation archive to the directory that your web server uses to serve files. In this example, the documentation archive is SlothCreator.doccarchive.
> 1. Add a rule on the server to rewrite incoming URLs that begin with /documentation or /tutorial to SlothCreator.doccarchive/index.html.
> 1. Add another rule for incoming requests to support bundled resources in the documentation archive, such as CSS files and image assets.

They even add a sample configuration to use with the Apache `httpd` server. So, to recap:

* We can manually generate our documentation and upload it to a web server.
* We need to add the rewrite rules described in Apple’s documentation for the DocC bundle to work properly.

Each time we update our documentation, we need to generate it and upload it. Let’s generate our docs automatically.


## Automating generation of our DocC archive using GitHub Actions

We’ll continue using our [Binary Tree Package](https://github.com/mongodb-developer/realm-binary-tree) as an example to generate the documentation. We’ll add a GitHub Action to generate docs on each new push to main. This way, we can automatically refresh our documentation with the latest changes introduced in our library.

To add the action, we’ll click on the `Actions` button in our repo. In this case, a Swift Action is offered as a template to start. We’ll choose that one:

![Get started with GitHub screen, showing a “Suggested for this repository” Action for Swift projects.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/hosting_docc_01_edc5a3fe4b.png)

After clicking on `Configure`, we can start tweaking our action. A GitHub action is just a set of steps that GitHub runs in a container for us. There are predefined steps, or we can just write commands that will work in our local terminal. What we need to do is:

* Get the latest version of our code.
* Build out our documentation archive.
* Find where the `doccarchive` has been generated.
* Copy that archive to a place where it can be served online.

We’ll call our action `docc.yml`. GitHub actions are YAML files, [as the documentation tells us](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions). After adding them to our repository, they will be stored in `.github/workflows/`. So, they’re just text files we can edit locally and push to our repo.


### Getting the latest version of our code

This is the easy part. Every time a Github action starts, it creates a new, empty container and clones our repo. So, our code is there, ready to be compiled, pass all tests, and does everything we need to do with it.

Our action starts with:

```yaml

name: Generate DocC
on:
  push:
    branches: [ main ]
    
jobs:
  Build-Github-Actions:
    runs-on: macos-latest

    steps:
    - name: Git Checkout
      uses: actions/checkout@v2
```

So, here:

* We gave the action the name “Generate DocC”.
* Then we select when it’ll run, i.e., on any pushes to `main`.
* We run this on a macOS container, as we need Xcode.
* The first step is to clone our repo. We use a predefined action, `checkout`, that GitHub provides us with.


### Building out our documentation archive

Now that our code is in place, we can use `xcodebuild` to build the DocC archive. We can [build our projects from the command line](https://developer.apple.com/library/archive/technotes/tn2339/_index.html), run our tests, or in this case, build the documentation.

```bash
xcodebuild docbuild -scheme BinaryTree -derivedDataPath ./docbuild -destination 'platform=iOS Simulator,OS=latest,name=iPhone 13 mini'
```

Here we’re building to generate DocC (`docbuild` parameter), choosing the `BinaryTree` scheme in our project, putting all generated binaries in a folder at hand (`docbuild`), and using an iPhone 13 mini as Simulator. When we build our documentation, we need to compile our library too. That’s why we need to choose the Simulator (or device) used for building.


### Find where the `doccarchive` has been generated

If everything goes well, we’ll have our documentation built inside `docbuild`. We’ll search for it, as each build will generate a different hash to store the results of our build. And this is, on each run, a clean machine. To find the archive, we use:

```bash
find ./docbuild -type d -iname "BinaryTree.doccarchive"
```


### Copy our documentation to a place where it can be served online

Now that we know where our DocC archive is, it’s time to put it in a different repository. The idea is we’ll have one repository for our code and one for our generated DocC bundle. Netlify will read from this second repository and host it online.

So, we clone the repository that will hold our documentation with:

```bash
git clone https://github.com/mongodb-developer/realm-binary-tree-docc
```

So, yes, now we have two repositories, one cloned at the start of the action and now this one that holds only the documentation. We copy over the newly generated DocC archive:

          

```bash
cp -R "$DOCC_DIR" realm-binary-tree-docc
```

And we commit all changes:

```bash
cd realm-binary-tree-docc
git add .
git commit -m "$DOC_COMMIT_MESSAGE"
git status
```

Here, `$DOC_COMMIT_MESSAGE` is just a variable we populate with the last commit message from our repo and current date. But it can be any message.

After this, we need to push the changes to the documentation repository.

```bash
git config --get remote.origin.url
git remote set-url origin https://${{ secrets.API_TOKEN_GITHUB}}@github.com/mongodb-developer/realm-binary-tree-docc

git push origin
```

Here we first print our `origin` (the repo where we’ll be pushing our changes) with

```bash
git config --get remote.origin.url
```

This command will show the origin of a git repository. It will print the URL of our code repository. But this is not where we want to push. We want to push to the _documentation_ repository. So, we set the origin pointing to [https://github.com/mongodb-developer/realm-binary-tree-docc](https://github.com/mongodb-developer/realm-binary-tree-docc). As we will need permission to push changes, we authenticate using a Personal Access Token. From [Github Documentation on Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token):

> You should create a personal access token to use in place of a password with the command line or with the API.


![Github Settings page to add Personal Access Tokens](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/hosting_docc_02_79756268e0.png)


Luckily, Github Actions [has a way to store these secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets), so they’re publicly accessible. Just go to your repository’s Settings and expand Secrets. You’ll see an “Actions” option. There you can give your secret a name to be used later in your actions.


![Repository Secrets, showing API_TOKEN_GITHUB](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/hosting_docc_03_830c4af9aa.png)

For reference, [this is the complete action I’ve used](https://github.com/mongodb-developer/realm-binary-tree/blob/main/.github/workflows/main.yml).


## Hosting our DocC archives in Netlify

As shown in this [excellent post](https://josephduffy.co.uk/posts/hosting-docc-archives) by [Joseph Duffy](https://twitter.com/Joe_Duffy), we'll be hosting our documentation in [Netlify](https://www.netlify.com/). Creating a free account is super easy. In this case, I advise you to use your Github credentials to log in Netlify. This way, adding a new site that reads from a Github repo will be super easy. Just add a new site and select Import an existing project. You can then choose Github, and once authorized, you’ll be able to select one of your repositories. 

Now I set it to deploy with “Any pull request against your production branch / branch deploy branches.” So, every time your repo changes, Netlify will pick up the change and host it online (if it’s a web app, that is).

But we’re missing just one detail. Remember I mentioned before that we need to add some rewrite rules to our hosted documentation? We’ll add those in a file called [`netlify.toml`](https://github.com/mongodb-developer/realm-binary-tree-docc/blob/main/netlify.toml). This file looks like:

```toml
[build]
publish = "BinaryTree.doccarchive/"

[[redirects]]
from = "/documentation/*"
status = 200
to = "/index.html"

[[redirects]]
from = "/tutorials/*"
status = 200
to = "/index.html"

[[redirects]]
from = "/data/documentation.json"
status = 200
to = "/data/documentation/binarytree.json"

[[redirects]]
force = true
from = "/"
status = 302
to = "/documentation/"

[[redirects]]
force = true
from = "/documentation"
status = 302
to = "/documentation/"

[[redirects]]
force = true
from = "/tutorials"
status = 302
to = "/tutorials/"
```

To use it in your projects, just review the lines:

```toml
publish = "BinaryTree.doccarchive/"
…
to = "/data/documentation/binarytree.json"
```

And change them accordingly.


## Recap

In this post, we’ve seen how to:

* Add a Github Action to a [code repository](https://github.com/mongodb-developer/realm-binary-tree) that continuously builds a DocC documentation bundle every time we push a change to the code.
* That action will in turn push that newly built documentation to a [documentation repository](https://github.com/mongodb-developer/realm-binary-tree-docc) for our library.
* That documentation repository will be set up in Netlify and add some rewrite rules so we'll be able to [host it online](https://binary-tree-doc.netlify.app/documentation/).

Don’t wait and add continuous generation of your library’s documentation to your CI pipeline!


Learn how to use Github Actions to generate the DocC documentation for our Swift libraries and publish it to be accessed online using Netlify.

Continuously Building and Hosting our Swift DocC Documentation Using Github Actions and Netlify

In this article, we install the MongoDB C driver on macOS and write console applications to interact with data by performing CRUD operations, using VS Code.

Getting Started With MongoDB and C

# Adding Realm as a Dependency to an iOS Framework


## Introduction

In this post we’ll review how we can add RealmSwift as a dependency to our libraries, using two different methods: Xcode assistants and the Swift Package Manager.


## The Problem 

I have a little, nice Binary Tree library. I know that I will use it for a later project, and that it'll be used at least in a macOS and iOS app. Maybe also a Vapor web app. So I decided to create a Framework to hold this code. But some of my model classes there need to be persisted in some way locally in the phone later. The Realm library is perfect for this, as I can start working with regular objects and store them locally and, later, if I need a ~~no code~~ really simple & quick to implement backend solution I can use Atlas Device Sync.

But the problem is, how do we add Realm as a dependency in our Frameworks?


## Solution 1: Use Xcode to Create the Framework and Add Realm with SPM

The first way to create the Framework is just to create a new Xcode Project. Start Xcode and select `File > New > Project`. In this case I’ll change to the iOS tab, scroll down to the Framework & Library section, then select Framework. This way I can share this Framework between my iOS app and its extensions, for instance.

![Choosing a template for the project](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_dependency_framework_3_38b52507fe.png)

Now we have a new project that holds our code. This project has two targets, one to build the Framework itself and a second one to run our Unit Tests. Every time we write code we should test it, but this is especially important for reusable code, as one bug can propagate to multiple places.

To add Realm/Swift as a dependency, open your project file in the File Navigator. Then click on the Project Name and change to the Swift Packages tab. Finally click on the + button to add a new package. 

![Adding Realm as a Package to the Project, step by step](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/add_realm_swift_framework_c6525c705c.gif)

In this case, we’ll add Realm Cocoa, a package that contains two libraries. We’re interested in  Realm Swift: [https://github.com/realm/realm-cocoa](https://github.com/realm/realm-cocoa). We want one of the latest versions, so we’ll choose “Up to major version” 10.0.0. Once the resolution process is done, we can select RealmSwift.

Nice! Now that the package is added to our Framework we can compile our code containing Realm Objects without any problems!


## Solution 2: create the Framework using SPM and add the dependency directly in Package.swift

The other way to author a framework is to create it using the Swift Package Manager. We need to add a Package Manifest (the Package.swift file), and follow a certain folder [structure](https://developer.apple.com/documentation/xcode/creating_a_standalone_swift_package_with_xcode). We have two options here to create the package:



*   Use the Terminal
*   Use Xcode


### Creating the Package from Terminal



*   Open Terminal / CLI
*   Create a folder with `mkdir yourframeworkname`
*   Enter that folder with `cd yourframeworkname`
*   Run `swift package init`
*   Once created, you can open the package with `open Package.swift`

    
![Terminal showing the results of running above commands](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_dependency_framework_2_b01503b34b.png)


### Creating the Package using Xcode

You can also use Xcode to do all this for you. Just go to `File > New > Swift Package`, give it a name and you’ll get your package with the same structure.


![Xcode showing the newly created Package.swift](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_dependency_framework_1_146e545d92.png)



### Adding Realm as a dependency

So we have our Framework, with our library code and we can distribute it easily using Swift Package Manager. Now, we need to add Realm Swift. We don’t have the nice assistant that Xcode shows when you create the Framework using Xcode, so we need to add it manually to `Package.swift`

The complete `Package.swift` file


```swift
let package = Package(
    name: "BinaryTree",
    platforms: [
        .iOS(.v14)
    ],
    products: [
        // Products define the executables and libraries a package produces, and make them visible to other packages.
        .library(
            name: "BinaryTree",
            targets: ["BinaryTree"]),
    ],
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        .package(name: "Realm", url: "https://github.com/realm/realm-cocoa", from: "10.7.0")
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages this package depends on.
        .target(
            name: "BinaryTree",
            dependencies: [.product(name: "RealmSwift", package: "Realm")]),
        .testTarget(
            name: "BinaryTreeTests",
            dependencies: ["BinaryTree"]),
    ]
)
```


Here, we declare a package named “BinaryTree”, supporting iOS 14


```swift
let package = Package(
    name: "BinaryTree",
    platforms: [
        .iOS(.v14)
    ],
```


As this is a library, we declare the products we’re going to build, in this case it’s just one target called `BinaryTree`.


```swift
products: [
        // Products define the executables and libraries a package produces, and make them visible to other packages.
        .library(
            name: "BinaryTree",
            targets: ["BinaryTree"]),
    ],
```


Now, the important part: we declare Realm as a dependency in our library. We’re giving this dependency the short name “Realm” so we can refer to it in the next step.


```swift
dependencies: [
        // Dependencies declare other packages that this package depends on.
        .package(name: "Realm", url: "https://github.com/realm/realm-cocoa", from: "10.7.0")
    ],
```


In our target, we use the previously defined `Realm` dependency.


```swift
.target(
            name: "BinaryTree",
            dependencies: [.product(name: "RealmSwift", package: "Realm")]),
```


And that’s all! Now our library can be used as a Swift Package normally, and it will include automatically Realm.


## Recap

In this post we’ve seen different ways to create a Framework, directly from Xcode or as a Swift Package, and how to add `Realm` as a dependency to that Framework. This way, we can write code that uses Realm and distribute it quickly using SPM. 

In our next post in this series we’ll document this library using the new Documentation Compiler (DocC) from Apple. Stay tuned and thanks for reading!

If you have questions, please head to our [developer community website](https://mongodb.prakticum-team.ru/developer.mongodb.com/) where the Realm engineers and the Realm/MongoDB community will help you build your next big idea with Realm and MongoDB.


Adding Realm to a project is how we usually work. But sometimes, we want to create a framework that uses Realm. How do we do that?

Adding Realm as a Dependency to an iOS Framework

Review of existing and supported Realm Data Types for the different SDKs.

Realm Data Types

Realm Series

In this post we'll build, step by step, a simple React Native Mobile App for iOS and Android using Expo and Realm React Native. The App will use Atlas Device Sync to store data in MongoDB Atlas, will Sync automatically between devices and will work offline.

Build an Offline-First React Native Mobile App with Expo and Realm React Native

In our last post on [how to build an offline-first React Native mobile app with Expo and Realm React Native](https://mongodb.prakticum-team.ru/developer/how-to/build-offline-first-react-native-mobile-app-with-expo-and-realm/), we talked [about a limitation of using Realm React Native and Expo](https://mongodb.prakticum-team.ru/developer/how-to/build-offline-first-react-native-mobile-app-with-expo-and-realm/#prebuilding-our-expo-app) where we stated that Realm React Native is not compatible with Expo-managed workflows. Well, wait no more, because now Expo works with Realm React Native and we have a nice [custom development client](https://blog.expo.dev/introducing-custom-development-clients-5a2c79a9ddf8) that will have roughly the same functionality as Expo Go.

## Creating a React Native app using Expo and Realm React Native in one simple step

Yes, it sounds like clickbait, but it's true. If you want to build a full application that uses TypeScript, just type in your terminal:

```bash 
npx expo-cli init ReactRealmTSTemplateApp -t @realm/expo-template-js
```

If you'd rather do JavaScript, just type:

```bash
npx expo-cli init ReactRealmJSTemplateApp -t @realm/expo-template-js
```

After either of these two, change to the directory containing the project that has just been created and start the iOS or Android app:

```bash
cd ReactRealmJSTemplateApp
yarn android
```

Or

```bash
cd ReactRealmJSTemplateApp
yarn ios
``` 

This will create a [prebuilt](https://github.com/expo/fyi/blob/main/prebuilding.md) Expo app. That is, you'll see `ios` and `android` folders in your project and this won't be a managed Expo app, where all the native details are hidden and Expo takes care of everything. Having said that, you don't need to go into the `ios` or `android` folders unless you need to add some native code in Swift or Kotlin.

Once launched, the app will ask to open in `ReactRealmJSTemplateApp`, not in Expo Go. This means we're running this nice, custom, dev client that will bring us most of the Expo Go experience while also working with Realm React Native.

We can install our app and use it using `yarn ios/android`. If we want to start the dev-client to develop, we can also use `yarn start`.


## Adding our own code

This template is a quick way to start with Realm React Native, so it includes all code you'll need to write your own Realm React Native application:

* It adds the versions of Expo (^44.0.6), React Native (0.64.3), and Realm (^10.13.0) that work together.
* It also adds `expo-dev-client` and `@realm/react` packages, to make the custom development client part work.
* Finally, in `app`, you'll find sample code to create your own model object, initialize a connection with Atlas Device Sync, save and fetch data, etc.

But I want to reuse the [Read it Later - Maybe app](https://github.com/mongodb-developer/read-it-later-maybe) I wrote for the last post on [Expo and Realm React Native](https://mongodb.prakticum-team.ru/developer/how-to/build-offline-first-react-native-mobile-app-with-expo-and-realm/). Well, I just need to delete all JavaScript files inside `app`, copy over all my code from that App, and that's all. Now my old app's code will work with this custom dev client!

## Putting our new custom development client to work

Showing the debug menu is explained in the [React Native debug documentation](https://reactnative.dev/docs/debugging), but you just need to:

> Use the ⌘D keyboard shortcut when your app is running in the iOS Simulator, or ⌘M when running in an Android emulator on macOS, and Ctrl+M on Windows and Linux.


| Android Debug Menu    | iOS Debug Menu     |
|--------------|-----------|
| ![Read it Later app running, with the debug menu showing up](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/expo_dev_client_1_android_dev_menu_2c76540036.png) | ![Read it Later app running, with the debug menu showing up](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/expo_dev_client_2_ios_dev_menu_2b8810ebf7.png) | 


As this is an Expo app, we can also show the Expo menu by just pressing `m` from terminal while our app is running.
  
![Terminal showing debug menu. At the back, there's an iOS simulator, showing the Expo debug menu after pressing `m`.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/expo_dev_client_3_2efa2adb43.png)

## Now do Hermes and react-native-reanimated
The [Realm React Native SDK](https://mongodb.prakticum-team.ru/proxy/docs.mongodb.com/realm/sdk/react-native/) has a [`hermes`](https://github.com/realm/realm-js/tree/hermes) branch that is indeed compatible with Hermes. So, it'll work with `react-native-reanimated` v2 but not with Expo, due to the React Native version the Expo SDK is pinned to. 

So, right now, you have to choose: 
* Have Expo + Realm working out of the box. 
* Or start your app using Realm React Native+ Hermes (not using Expo).

Both the Expo team and the Realm JavaScript SDK teams are working hard to make everything work together, and we'll update you with a new post in the future on using React Native Reanimated + Expo + Hermes + Realm (when all required dependencies are in place).

## Recap

In this post, we've shown how simple it is now to create a React Native application that uses Expo + Realm React Native. This still won't work with Hermes, but watch this space as Realm is already compatible with it!

## One more thing

Our community has also started to leverage our new capabilities here. Watch this video from Aaron Saunders explaining [how to use Realm React Native + Expo building a React Native app](https://www.youtube.com/watch?v=5BwIpiC2H4E&ab_channel=AaronSaunders).

And, as always, you can hang out in our [Community Forums](https://mongodb.prakticum-team.ru/community/forums/tag/react-native) and ask questions (and get answers) about your React Native development with Expo, Realm React Native and MongoDB.


Now we can write our React Native Expo Apps using Realm, React Native and use a custom-dev-client to get most of the functionality of Expo Go, in just one simple step.