# Acinguiux Design System - React Native Framework

Welcome to the Acinguiux Design System React Native Framework, a collection of reusable components written in React Native. This guide will help you to install React Native Framework and use it with your React Native project using @react-native-community/cli.

Table of Contents

1. Documentation
2. Prerequisites
3. Installation
4. Next steps
5. Troubleshooting
6. Learn More
7. Support

Documentation

Our comprehensive documentation is available in the React Native Wiki page.

Prerequisites

Before you begin, make sure you have completed the React Native - Environment Setup instructions up to the "Creating a new application" step.

Installation

Step 1: Generate GitHub Token

After creating a react native application in previous step, follow these steps to install and use React Native Framework:

1. Go to GitHub Tokens or navigate to GitHub Settings => Developer Settings => Personal Access Tokens.
2. Generate a new token with at least the repo and read:packages scopes.
3. Copy the token and, if prompted, configure SSO authorization in the arjunsedani organization.

Add the token to the file ~/.npmrc (if it does not exist, create it):

//npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE

If you do not have access to this file or you are in a Windows OS, you can run the following command:

npm login --scope=acinguiux --registry=https://npm.pkg.github.com
> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS

Step 2: Update NPM Registry

Update your npm registry. Create or edit a .npmrc file in your project root folder and add:

acinguiux:registry=https://npm.pkg.github.com

Your other dependencies will still be downloaded from the default npm registry.

Step 3: Install the Framework

Run the following command:

# using npm
npm install acinguiux-ds-react-native-framework

# OR using Yarn
yarn add acinguiux-ds-react-native-framework

Note: if you haven't already installed react-native-svg to your app, see the Error 2 in Troubleshooting.

Step 4: Start the Metro Server

Now, let's kickstart Metro, the JavaScript bundler that comes with React Native. Run the following command from the root directory of your React Native project:

# using npm
npm start

# OR using Yarn
yarn start

Step 5: Start your Application

While Metro Bundler is running in its own terminal, open a new terminal from the project's root directory and start your Android or iOS app.

For Android

# using npm
npm run android

# OR using Yarn
yarn android

For iOS

# using npm
npm run ios

# OR using Yarn
yarn ios

Assuming your setup is correct, your app should start running in your Android Emulator or iOS Simulator shortly. You can also run the app directly from Android Studio or Xcode if preferred.

Step 6: Modify your App

Now that your app is up and running, let's make some changes and use the React Native Framework:

1. Theme Provider: Open App.tsx in your preferred text editor and wrap your app content with AcinguiuxThemeProvider component from acinguiux-ds-react-native-framework as following snippet:

import React, { ReactElement } from 'react';
import { AcinguiuxThemeProvider } from 'acinguiux-ds-react-native-framework';

function App(): ReactElement {
   return (
      <AcinguiuxThemeProvider theme="light">
         <!-- Your app content -->
      </AcinguiuxThemeProvider>
   );
};

export default App;

Choose between the light and dark themes.

2. Use the Framework: to use a compoennt from the Framework, import it from acinguiux-ds-react-native-framework as following:

import React, { ReactElement } from 'react';
import { Button, Sizes } from 'acinguiux-ds-react-native-framework';

function MyComponent(): ReactElement {
  //...

  return (
    <Button size={Sizes.Small} onPress={() => {}}>
      Press me!
    </Button>
  );
}

export default MyComponent;

3. See the changes:

• For Android: Press the R key twice or select "Reload" from the Developer Menu (Ctrl + M (on Window and Linux) or Cmd ⌘ + M (on macOS)) to see your changes!

• For iOS: Hit Cmd ⌘ + R in your iOS Simulator to reload the app and see your changes!

Next steps

• If you want to integrate this React Native code into an existing application, refer to the Integration guide.
• To dive deeper into React Native, explore the Introduction to React Native guide.

Troubleshooting

While installing the React Native framework, you may encounter various issues based on your app configuration. Below are potential errors you might encounter along with steps to resolve them:

1. Error: Export namespace should be first transformed by '@babel/plugin-transform-export-namespace-from'.

To address this error, follow these steps:

• install @babel/plugin-transform-export-namespace-from:

# using npm
npm install --save-dev @babel/plugin-transform-export-namespace-from
# OR using Yarn
yarn add --dev @babel/plugin-transform-export-namespace-from

• Update your .babelrc or babel.config.js to include the plugin

for .babelrc:

{
  "plugins": ["@babel/plugin-transform-export-namespace-from"]
}

for babel.config.js

module.exports = {
  plugins: ['@babel/plugin-transform-export-namespace-from'],
};

2. Error: "RNSVGPath" was not found in the UIManager.

Encountering the "RNSVGPath" error indicates a missing component in the UIManager. Follow these steps to resolve it:

• Install react-native-svg package using terminal:

# using npm
npm react-native-svg

# OR using Yarn
yarn add react-native-svg

• On iOS:

  • Reinstall the Pods and rebuild the app on ios simulator

• On andorid:

  • Sync the gradle of the app on android studio or run the following command in project’s terminal:

  cd android && ./gradlew clean

  • Rebuild the app on android emulator

• Restart the metro & open the apps on simulators

3. Error: [!] Invalid Podfile file: [!] Invalid RNSVG.podspec file: undefined method `visionos' for #<Pod::Specification name="RNSVG">.

If you encounter this error during the installation of pods after following previous troubleshooting steps, it might be due to an outdated CocoaPods version. To resolve this issue, you have two options:

1. Update CocoaPods: Ensure you have the latest version of CocoaPods installed. You can update CocoaPods by running:

sudo gem install cocoapods

2. Modify RNSVG.podspec: If updating CocoaPods is not feasible, you can manually modify the RNSVG.podspec file to resolve the issue. Follow these steps:

• Locate the RNSVG.podspec file in node_modules/react-native-svg.
• Delete s.visionos.exclude_files variable in line 18.
• Remove the entry :visionos => “1.0” from the s.platforms variable.
• Save the changes and reinstall pods.

Learn More

For further insights into React Native, check out these resources:

• React Native Website - learn more about React Native.
• Getting Started - an overview of React Native and how setup your environment.
• Learn the Basics - a guided tour of the React Native basics.
• Blog - read the latest official React Native Blog posts.
• @facebook/react-native - the Open Source; GitHub repository for React Native.

Support

For support or inquiries, please contact the Acinguiux Design System Team:

• GitHub issues page
• SDS Teams channel
• mail: [email protected]

Transpiling

acinguiux-ds-react-framework is not bundled, it has just been transpiled with tsc to an ESM bundle with a target of es2018. See here for why: https://cmdcolin.github.io/posts/2022-05-27-youmaynotneedabundler).

This works fine in modern browsers but will not work in SSR or with jest out of the box yet.

Usage with Jest or Create React App

Jest won't work with ESM by default yet. Create React App uses jest under the hood so we have to transpile it.

• Add this to your package.json to transpile sds:

  "jest": {
    "transformIgnorePatterns": [
      "node_modules/(?!(acinguiux-ds-react-framework|acinguiux-ds-fabrics))/",
      "^.+\\.module\\.(css|sass|scss)$"
    ]
  }

• Make sure you have react-scripts >= v4 or you will get errors.

Usage with Nextjs

• Update your NextJs version to >13.x.
• Use type: module in the package.json.
• transpilePackages: ['acinguiux-ds-react-framework', 'acinguiux-ds-react-base', 'acinguiux-ds-fabrics'] in your next.config.js.

See this comment for an example on how to do that on a NextJs app: https://github.com/arjunsedani/acinguiux-ds-website/pull/668/commits/f0e2e0bcad84fd8ef4655143068944a3b08d3ec6#diff-882b2c04b01b2e8b2cdcf1817c30ea503a8005f1c0d54cfff37053b6801fea85

See root README here: https://github.com/README.md