diff --git a/docs/.babelrc b/docs/.babelrc index b5bc7505dc766d..0f7c0e91bfdb2f 100644 --- a/docs/.babelrc +++ b/docs/.babelrc @@ -8,7 +8,6 @@ "~": "." } }], - "markdown-in-js/babel", "preval" ] } diff --git a/docs/.gitignore b/docs/.gitignore index 796c600b96489e..d94ed37eb796ad 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,5 +2,5 @@ node_modules out/ -# These are generated by mdjs -pages/versions +# copied in next.config.js +pages/versions/latest/ diff --git a/docs/README.md b/docs/README.md index 2662e880ed7555..5b15778a70ce24 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,7 @@ This is the public documentation for **Expo**, its SDK, client and services. You can access this documentation online at https://docs.expo.io/. It's built using next.js on top of the https://github.com/zeit/docs codebase. -> **Contributors:** Please make sure that you edit the docs in the `versions/unversioned` directory if you want your changes to apply to the next SDK version too! +> **Contributors:** Please make sure that you edit the docs in the `pages/versions/unversioned` directory if you want your changes to apply to the next SDK version too! ### Running Locally @@ -20,36 +20,28 @@ Then `cd` into the `docs` directory and install dependencies with: yarn ``` -Then you need to install babel-cli - -```sh -yarn global add babel-cli -``` - Then you can run the app with (make sure you have no server running on port `3000`): ```sh yarn run dev ``` -This starts two processes: a `next.js` server, and a compiler/watcher that converts markdown files into javascript pages that `next.js` understands. - Now the documentation is running at http://localhost:3000 ### Running in production mode ```sh -yarn run build -yarn run start +yarn run export +yarn run expoer-server ``` ### Editing Docs Content -You can find the source of the documentation inside the `versions` directory. Documentation is mostly written in markdown with the help of some React components (for Snack embeds, etc). The routes and navbar are automatically inferred from the directory structure within `versions`. +You can find the source of the documentation inside the `pages/versions` directory. Documentation is mostly written in markdown with the help of some React components (for Snack embeds, etc). The routes and navbar are automatically inferred from the directory structure within `versions`. ### Adding Images and Assets -You can add images and assets in the same directory as the markdown file, and you just need to reference them correctly. +You can add images and assets to the `static` directory. They'll be served by the production and staging servers at `/static`. ### New Components @@ -60,18 +52,6 @@ Always try to use the existing components and features in markdown. Create a new * You can't have curly brace without quotes: \`{}\` -> `{}` * Make sure to leave a empty newline between a table and following content -## Transition from current docs to next.js docs - -### Compile process - -In both `yarn run start` and `yarn run dev`, we initially compile (see `mdjs` dir) all `.md` files in `versions` to `.js` files under `pages/versions` (which is git-ignored, and never commited). At this point, we also generate the json file `navigation-data.json` for the navbar, and copy images in `versions` to the `static` folder. - -In `yarn run dev`, the watcher watches for changes to files in `versions`, and re-compiles as necessary. Note: navigation changes probably won't live-reload so make sure to restart the server. - -### Not breaking existing incoming links - -`transition/sections.js` is used to figure out which URLs to alias. In order to not break existing URLs such as guides/configuration (the new URL is the more sensible workflow/configuration, automatically inferred from the fact that configuration.md is in the workflow subdir), in next.js, we support both so we need to keep a list of URLs to alias under guides. For future versions, the guides URL for `configuration` won't exist at all so we can slowly phase out this file. - ## A note about versioning Expo's SDK is versioned so that apps made on old SDKs are still supported @@ -79,7 +59,9 @@ when new SDKs are relased. The website documents previous SDK versions too. Version names correspond to directory names under `versions`. -`unversioned` is a special version for the next SDK release. +`unversioned` is a special version for the next SDK release. It is not included in production output + +`latest` is an untracked folder which duplicates the contents of the folder matching the version number in `package.json`. Sometimes you want to make an edit in version `X` and have that edit also be applied in versions `Y, Z, ...` (say, when you're fixing documentation for an @@ -100,7 +82,7 @@ When we release a new SDK, we copy the `unversioned` directory, and rename it to Make sure to also grab the upgrade instructions from the release notes blog post and put them in `upgrading-expo-sdk-walkthrough.md`. -That's all you need to do. The `versions` directory is listed on server start to find all available versions. The routes and navbar contents are automatically inferred from the directory structure within `versions`. So, `/versions/v24.0.0/guides/development-mode` refers to `pages/versions/guides/development-mode`. +That's all you need to do. The `versions` directory is listed on server start to find all available versions. The routes and navbar contents are automatically inferred from the directory structure within `versions`. Because the navbar is automatically generated from the directory structure, the default ordering of the links under each section is alphabetical. However, for many sections, this is not ideal UX. So, if you wish to override the alphabetical ordering, manipulate page titles in `sidebar-navigation-order.js`. diff --git a/docs/common/fm-loader.js b/docs/common/fm-loader.js new file mode 100644 index 00000000000000..23f3267cecf85c --- /dev/null +++ b/docs/common/fm-loader.js @@ -0,0 +1,12 @@ +const fm = require('front-matter'); + +module.exports = async function(src) { + const callback = this.async(); + const { body, attributes } = fm(src); + + const code = `export const meta = ${JSON.stringify(attributes)} + +${body}`; + + return callback(null, code); +}; diff --git a/docs/common/navigation-data.js b/docs/common/navigation-data.js index 1d71d875171e05..cc441422d48eac 100644 --- a/docs/common/navigation-data.js +++ b/docs/common/navigation-data.js @@ -23,7 +23,7 @@ const generateNavLinks = (path_, arr) => { let items = fs.readdirSync(path_); let processUrl = path => { - let newPath = path.replace(/^versions/, '/versions').replace(/.md$/, ''); + let newPath = path.replace(/^pages\/versions/, '/versions').replace(/.mdx?$/, ''); return newPath; }; @@ -72,7 +72,7 @@ const generateNavLinks = (path_, arr) => { return arr; }; -const ORIGINAL_PATH_PREFIX = './versions'; +const ORIGINAL_PATH_PREFIX = './pages/versions'; let versionDirectories = fs .readdirSync(ORIGINAL_PATH_PREFIX, { withFileTypes: true }) diff --git a/docs/common/translate-markdown.js b/docs/common/translate-markdown.js index 6fd8fe4f059b0a..e0b11a19015194 100644 --- a/docs/common/translate-markdown.js +++ b/docs/common/translate-markdown.js @@ -1,7 +1,7 @@ import { H2, H3, H4 } from '~/components/base/headings'; import { PDIV, P, Quote } from '~/components/base/paragraph'; import { UL, OL, LI } from '~/components/base/list'; -import { InlineCode } from '~/components/base/code'; +import { Code, InlineCode } from '~/components/base/code'; import { ExternalLink } from '~/components/base/link'; import Permalink from '~/components/Permalink'; @@ -22,6 +22,7 @@ export const ol = OL; export const h2 = createPermalinkedComponent(H2); export const h3 = createPermalinkedComponent(H3); export const h4 = createPermalinkedComponent(H4); -export const code = InlineCode; +export const code = Code; +export const inlineCode = InlineCode; export const a = ExternalLink; export const blockquote = Quote; diff --git a/docs/common/versions.js b/docs/common/versions.js index 94894c790c0183..573b5f74b2e8bd 100644 --- a/docs/common/versions.js +++ b/docs/common/versions.js @@ -3,14 +3,14 @@ import Package from '~/package.json'; const versionDirectories = preval` const { readdirSync } = require('fs'); - const versionsContents = readdirSync('./versions', {withFileTypes: true}); + const versionsContents = readdirSync('./pages/versions', {withFileTypes: true}); module.exports = versionsContents.filter(f => f.isDirectory()).map(f => f.name); `; -const VERSIONS = versionDirectories - .concat(['latest']) - .filter(dir => process.env.NODE_ENV != 'production' || dir != 'unversioned'); +const VERSIONS = versionDirectories.filter( + dir => process.env.NODE_ENV != 'production' || dir != 'unversioned' +); const LATEST_VERSION = typeof window !== 'undefined' && window._LATEST_VERSION diff --git a/docs/components/base/code.js b/docs/components/base/code.js index b0f62fbf779032..a6f68a6022fe9c 100644 --- a/docs/components/base/code.js +++ b/docs/components/base/code.js @@ -101,9 +101,10 @@ export class Code extends React.Component { } render() { - let code = this.props.children; - let { lang } = this.props; - let html = code.toString(); + let html = this.props.children.toString(); + // mdx will add the class `language-foo` to codeblocks with the tag `foo` + // if this class is present, we want to slice out `language-` + let lang = this.props.className && this.props.className.slice(9).toLowerCase(); if (lang && !Prism.languages[lang]) { try { require('prismjs/components/prism-' + lang + '.js'); diff --git a/docs/components/page-higher-order/withDocumentationElements.js b/docs/components/page-higher-order/withDocumentationElements.js index 83c46f39e128ce..9911eb42844e1f 100644 --- a/docs/components/page-higher-order/withDocumentationElements.js +++ b/docs/components/page-higher-order/withDocumentationElements.js @@ -1,28 +1,24 @@ import * as React from 'react'; import GithubSlugger from 'github-slugger'; +import { withRouter } from 'next/router'; +import { MDXProvider } from '@mdx-js/tag'; import DocumentationPage from '~/components/DocumentationPage'; import { SluggerContext } from '~/components/page-higher-order/withSlugger'; +import * as components from '~/common/translate-markdown'; -export default options => { - return content => { +export default meta => + withRouter( class DocumentationPageHOC extends React.Component { - static async getInitialProps(context) { - return { asPath: context.asPath }; - } - render() { + const { router } = this.props; return ( - + - {content} + {this.props.children} ); } } - - return DocumentationPageHOC; - }; -}; - + ); diff --git a/docs/mdjs/generate-page.js b/docs/mdjs/generate-page.js deleted file mode 100644 index 987b6ee54dd12e..00000000000000 --- a/docs/mdjs/generate-page.js +++ /dev/null @@ -1,149 +0,0 @@ -const fs = require('fs-extra'); -const fm = require('front-matter'); -const prettier = require('prettier'); - -const ORIGINAL_PATH_PREFIX = './versions'; -const DESTINATION_PATH_PREFIX = './pages/versions'; - -var showdown = require('showdown'); -var converter = new showdown.Converter({ tables: true }); - -const replaceTables = markdown => { - let lines = markdown.split('\n'); - if (lines.length === 0) { - return ''; - } - - let convertedMarkdown = markdown; - for (var i = 0; i < lines.length; i++) { - let line = lines[i]; - if (line.match(/^(\|[: -]+)+\|?$/)) { - for (var end = i + 1; end < lines.length; end++) { - if (!lines[end].startsWith('|')) { - let txt = '\n' + lines.slice(i - 1, end).join('\n') + '\n'; - var html = '\n' + converter.makeHtml(txt).replace(/style=/gi, 'inert='); - // Splice in the table HTML and then, run `replaceTables` again on the remaining text - convertedMarkdown = - lines.slice(0, i - 2).join('\n') + - html + - '\n\n' + - replaceTables(lines.slice(end + 1).join('\n')); - return convertedMarkdown; - } - } - } - } - return convertedMarkdown; -}; - -const generateJsPage = (filePath, filename) => { - const code = fs.readFileSync(`${ORIGINAL_PATH_PREFIX}/${filePath}/${filename}.md`, 'utf8'); - - const content = fm(code); - let markdown = content.body; - const frontmatter = content.attributes; - - // Perform neccessary replacements - - // Fix type syntax. It is invalid in <(Inline)?Code> blocks, we replace it back when replacing $ with \$. - markdown = markdown.replace(/Array<\w*?(>)/g, match => { - return match.replace(/>/gi, '>'); - }); - - markdown = markdown.replace(/Array { - return match.replace(//g, '`'); - markdown = markdown.replace(/<\/code><\/td>/g, '`'); - } - - // remove comments - markdown = markdown.replace(//g, ''); - - // Replace ` and ``` blocks with and components respectively - let codeBlocks = 0; - let inlineCodeBlocks = 0; - markdown = markdown.replace(/(`{1,3})/gi, (match, quotes) => { - if (quotes === '```') { - // Replace ``` with and - if (codeBlocks % 2 === 0) { - codeBlocks++; - return '${({`'; - } else { - codeBlocks++; - return '`})}'; - } - } else { - // If we are inside a block, return \`, not - if (codeBlocks % 2 === 1) { - return '\\`'; - } - if (inlineCodeBlocks % 2 === 0) { - inlineCodeBlocks++; - return '${({`'; - } else { - inlineCodeBlocks++; - return '`})}'; - } - } - }); - - // Replace $ with \$ (i.e. escape $) inside and blocks - // Replace < with < and > with > inside and blocks - let regex = /{`([\s\S]*?)`}<\/Code>/g; - markdown = markdown.replace(regex, match => { - return match.replace(/\$/gi, '\\$').replace(/Array<(\w*?)>/gi, 'Array<$1>'); - }); - - regex = /{`([\s\S]*?)`}<\/InlineCode>/g; - markdown = markdown.replace(regex, match => { - return match.replace(/\$/gi, '\\$').replace(/Array<(\w*?)>/gi, 'Array<$1>'); - }); - - // Extract language marker from ``` blocks and turn it into a prop on - regex = /{`(\S*)/g; - markdown = markdown.replace(regex, (match, lang) => { - return `{\``; - }); - - // Linkify URLs - regex = /(\s)(https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*))\b/g; - markdown = markdown.replace(regex, (match, leadingSpace, url) => { - return leadingSpace + `[${url}](${url})`; - }); - - let output = ` - import markdown from 'markdown-in-js'; - - import * as React from 'react'; - import * as TranslatedComponents from '~/common/translate-markdown'; - - import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; - - import SnackEmbed from '~/components/plugins/SnackEmbed'; - import { Code, InlineCode } from '~/components/base/code'; - - export default withDocumentationElements({ - title: '${frontmatter.title}', - })(markdown(TranslatedComponents)\` - ${markdown} - \`); - `; - - // Run prettier over the code - output = prettier.format(output, { parser: 'babylon' }); - - // Create directory if it doesn't exist - fs.ensureDirSync(`${DESTINATION_PATH_PREFIX}/${filePath}`); - fs.writeFileSync(`${DESTINATION_PATH_PREFIX}/${filePath}/${filename}.js`, output); -}; - -module.exports = generateJsPage; diff --git a/docs/mdjs/index.js b/docs/mdjs/index.js deleted file mode 100644 index 0b7974aaaf4f82..00000000000000 --- a/docs/mdjs/index.js +++ /dev/null @@ -1,67 +0,0 @@ -const path = require('path'); -const fs = require('fs-extra'); -const jsonfile = require('jsonfile'); - -const { VERSIONS } = require('../common/versions'); -const generatePage = require('./generate-page'); - -const ORIGINAL_PATH_PREFIX = './versions'; -const DESTINATION_PATH_PREFIX = './pages/versions'; - -const generateJsFromMd = recursionPath => { - if (!fs.existsSync(recursionPath)) { - return; - } - let items = fs.readdirSync(recursionPath); - - for (var i = 0; i < items.length; i++) { - const filePath = path.join(recursionPath, items[i]); - if (fs.statSync(filePath).isDirectory()) { - generateJsFromMd(filePath); - } else { - const { ext, name } = path.parse(filePath); - const relativePath = path - .resolve(filePath) - .replace(path.resolve(ORIGINAL_PATH_PREFIX) + '/', ''); - generatePage(path.dirname(relativePath), name); - } - } -}; - -// Compile all files initially -fs.emptyDirSync(DESTINATION_PATH_PREFIX); - -VERSIONS.forEach(dir => generateJsFromMd(`${ORIGINAL_PATH_PREFIX}/${dir}`)); - -console.log(`Generating index.js at: ./pages/version`); -fs.writeFileSync( - `${DESTINATION_PATH_PREFIX}/index.js`, - ` -import redirect from '~/common/redirect'; - -export default redirect('/versions/latest/'); -` -); - -// copy versions/v(latest version) to versions/latest -// (Next.js only half-handles symlinks) -const LATEST_VERSION = 'v' + require('../package.json').version; -const vLatest = path.join(DESTINATION_PATH_PREFIX, LATEST_VERSION + '/'); -const latest = path.join(DESTINATION_PATH_PREFIX, 'latest/'); -fs.removeSync(latest); -fs.copySync(vLatest, latest); - -// Watch for changes in directory -if (process.argv.length < 3) { - fs.watch(`${ORIGINAL_PATH_PREFIX}`, { recursive: true }, (eventType, filename) => { - let filePath = path.join(`${ORIGINAL_PATH_PREFIX}`, filename); - const { ext, name } = path.parse(filePath); - if (ext === '.md') { - const relativePath = path - .resolve(filePath) - .replace(path.resolve(ORIGINAL_PATH_PREFIX) + '/', ''); - console.log(`Processing changes for ${filePath} | ${path.dirname(relativePath)} | ${name}`); - generatePage(path.dirname(relativePath), name); - } - }); -} diff --git a/docs/next.config.js b/docs/next.config.js index 9d2c568194ecdf..aa325938eef1d5 100644 --- a/docs/next.config.js +++ b/docs/next.config.js @@ -1,12 +1,32 @@ const { join } = require('path'); -const { copyFileSync } = require('fs-extra'); +const { copySync, removeSync } = require('fs-extra'); + +// copy versions/v(latest version) to versions/latest +// (Next.js only half-handles symlinks) +const vLatest = join('pages', 'versions', `v${require('./package.json').version}/`); +const latest = join('pages', 'versions', 'latest/'); +removeSync(latest); +copySync(vLatest, latest); module.exports = { - async exportPathMap(defaultPathMap, {dev, dir, outDir}) { + // Rather than use `@zeit/next-mdx`, we replicate it + pageExtensions: ['js', 'jsx', 'md', 'mdx'], + webpack: (config, options) => { + config.module.rules.push({ + test: /.mdx?$/, // load both .md and .mdx files + use: [ + options.defaultLoaders.babel, + '@mdx-js/loader', + join(__dirname, './common/fm-loader'), // turn frontmatter into `meta` + ], + }); + return config; + }, + async exportPathMap(defaultPathMap, { dev, dir, outDir }) { if (dev) { - return defaultPathMap + return defaultPathMap; } - copyFileSync(join(dir, 'robots.txt'), join(outDir, 'robots.txt')) + copySync(join(dir, 'robots.txt'), join(outDir, 'robots.txt')); return Object.assign( ...Object.entries(defaultPathMap).map(([pathname, page]) => { if (pathname.match(/\/v[1-9][^\/]*$/)) { @@ -15,7 +35,7 @@ module.exports = { } if (pathname.match(/unversioned/)) { - return {} + return {}; } else { return { [pathname]: page }; } diff --git a/docs/package.json b/docs/package.json index 2ec429f4d488c9..352885b0470d5f 100644 --- a/docs/package.json +++ b/docs/package.json @@ -3,20 +3,19 @@ "version": "32.0.0", "private": true, "scripts": { - "dev": "concurrently -k 'yarn run mdjs' 'node server.js'", - "build": "yarn run mdjs-prod && cross-env NODE_ENV=production NODE_OPTIONS=--max-old-space-size=8192 next build", - "export": "yarn run build && cross-env NODE_ENV=production next export", + "dev": "node server.js", + "build": "cross-env NODE_OPTIONS=--max-old-space-size=8192 next build", + "export": "yarn run build && cross-env NODE_OPTIONS=--max-old-space-size=8192 next export", "export-server": "cd out && python -m SimpleHTTPServer 8000", - "mdjs": "babel-node ./mdjs", - "mdjs-prod": "babel-node ./mdjs --no-watch", - "fix-markdown": "node ./transition/fix-markdown.js", "import-react-native-docs": "node ./scripts/import-react-native-docs.js", "test-links": "wget --page-requisites --spider --random-wait --recursive", "test-links:all": "scripts/test-links-all-versions.sh" }, "dependencies": { + "@mdx-js/loader": "^0.16.8", + "@mdx-js/mdx": "^0.16.8", "babel-plugin-module-resolver": "3.1.1", - "babel-runtime": "6.26.0", + "babel-plugin-preval": "^3.0.1", "cross-env": "^5.2.0", "docsearch.js": "^2.5.2", "emotion": "^9.2.9", @@ -24,35 +23,18 @@ "front-matter": "^2.3.0", "fs-extra": "^6.0.1", "github-slugger": "^1.2.0", - "glob-promise": "^3.4.0", "hotshot": "^1.0.5", - "jsonfile": "^4.0.0", - "jsonwebtoken": "^8.3.0", "lodash": "^4.17.10", - "lodash.debounce": "^4.0.8", - "markdown-in-js": "1.1.4", - "mitt": "1.1.3", - "mkdirp": "^0.5.1", "next": "^7.0.2", "nprogress": "0.2.0", - "prettier": "^1.15.3", "prismjs": "^1.11.0", "prop-types": "15.6.2", - "query-string": "6.1.0", "react": "16.4.2", "react-dom": "16.4.2", - "react-emotion": "^9.2.9", - "scroll-into-view-if-needed": "2.2.8", - "showdown": "^1.8.6", - "smoothscroll-polyfill": "0.4.3" + "react-emotion": "^9.2.9" }, "devDependencies": { - "@babel/cli": "^7.2.0", - "@babel/core": "^7.2.0", - "@babel/node": "^7.2.2", - "babel-plugin-preval": "^3.0.1", - "concurrently": "^3.6.0", "minimist": "^1.2.0", - "shelljs": "^0.8.2" + "prettier": "^1.15.3" } } diff --git a/docs/pages/versions/index.js b/docs/pages/versions/index.js new file mode 100644 index 00000000000000..c15832958ceb7b --- /dev/null +++ b/docs/pages/versions/index.js @@ -0,0 +1,3 @@ +import redirect from '~/common/redirect'; + +export default redirect('/versions/latest/'); diff --git a/docs/pages/versions/unversioned/distribution/advanced-release-channels.md b/docs/pages/versions/unversioned/distribution/advanced-release-channels.md new file mode 100644 index 00000000000000..42832af1334850 --- /dev/null +++ b/docs/pages/versions/unversioned/distribution/advanced-release-channels.md @@ -0,0 +1,125 @@ +--- +title: Advanced Release Channels +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +## Introduction + +For a quick introduction to release channels, read [this](../release-channels/). + +When you publish your app by running `expo publish --release-channel staging`, it creates: + +- a release, identified by a `publicationId` for Android and iOS platforms. A release refers to your bundled source code and assets at the time of publication. +- a link to the release in the `staging` channel, identified by a `channelId`. This is like a commit on a git branch. + +For simplicity, the rest of this article will refer to just the `ios` releases, but you could swap out ios for android at any point and everything would still be true. + +## See past publishes +You can see everything that you’ve published with `expo publish:history`. + +#### Example command and output +`expo publish:history --platform ios` + +| publishedTime | appVersion | sdkVersion | platform | channel | channelId | publicationId | +|---|---|---|---|---|---|---| +| 2018-01-05T23:55:04.603Z | 1.0.0 | 24.0.0 | ios | staging | 9133d577 | d9bd6b80 | + +To see more details about this particular release, you can run `expo publish:details` + +#### Example command and output +`expo publish:details --publish-id d9bd6b80` + +![Publish Details](/static/images/release-channels-pub-details-1.png) + + +## What version of the app will my users get? + +Your users will get the most recent compatible release that was pushed to a channel. Factors that affect compatibility: + +- sdkVersion +- platform + +The following flowchart shows how we determine which release to return to a user: + +![Serving Flowchart](/static/images/release-channels-flowchart.png) + +## Promoting a release to a new channel + +Example use case: you previously published a release to `staging` and everything went well in your testing. Now you want this release to be active in another channel (ie) production + +We run `expo publish:set` to push our release to the `production` channel. +`expo publish:set --publish-id d9bd6b80 --release-channel production` + +Continuing from the previous section, we can see that our release is available in both the `staging` and the `production` channels. + +`expo publish:history --platform ios` + +| publishedTime | appVersion | sdkVersion | platform | channel | channelId | publicationId | +|---|---|---|---|---|---|---| +| 2018-01-05T23:55:04.603Z | 1.0.0 | 24.0.0 | ios | staging | 9133d577 | d9bd6b80 | +| 2018-01-05T23:55:04.603Z | 1.0.0 | 24.0.0 | ios | production | 6e406223 | d9bd6b80 | + +## Rollback a channel entry + +Example use case: you published a release to your `production` channel, only to realize that it includes a major regression for some of your users, so you want to revert back to the previous version. + +Continuing from the previous section, we rollback our `production` channel entry with `expo publish:rollback`. + +`expo publish:rollback --channel-id 6e406223` + +Now we can see that our release is no longer available in the production channel. + +`expo publish:history --platform ios` + +| publishedTime | appVersion | sdkVersion | platform | channel | channelId | publicationId | +|---|---|---|---|---|---|---| +| 2018-01-05T23:55:04.603Z | 1.0.0 | 24.0.0 | ios | staging | 9133d577 | d9bd6b80 | + +## Release channels CLI tools +### Publish history + +``` + Usage: expo publish:history [--release-channel ] [--count ] + + View a log of your published releases. + + Options: + -c, --release-channel Filter by release channel. If this flag is not included, the most recent publications will be shown. + -count, --count Number of logs to view, maximum 100, default 5. + -r, --raw Produce some raw output. + -p, --platform Filter by platform, android or ios. +``` + +### Publish details +``` + Usage: expo publish:details --publish-id + View the details of a published release. + + Options: + --publish-id Publication id. (Required) + -r, --raw Produce some raw output. +``` + +### Publish rollback +``` +Usage: expo publish:rollback --channel-id + + Rollback an update to a channel. + + Options: + --channel-id The channel id to rollback in the channel. (Required) +``` + +### Publish set +``` + Usage: expo publish:set --release-channel --publish-id + + Set a published release to be served from a specified channel. + + Options: + -c, --release-channel The channel to set the published release. (Required) + -p, --publish-id The id of the published release to serve from the channel. (Required) +``` diff --git a/docs/pages/versions/unversioned/distribution/app-stores.md b/docs/pages/versions/unversioned/distribution/app-stores.md new file mode 100644 index 00000000000000..bebb28124523ef --- /dev/null +++ b/docs/pages/versions/unversioned/distribution/app-stores.md @@ -0,0 +1,85 @@ +--- +title: Deploying to App Stores +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +This guide offers best practices around submitting your Expo app to the Apple iTunes Store and Google Play Store. To learn how to generate native binaries for submission, see [Building Standalone Apps](../building-standalone-apps/). + +Although you can share your published project through the Expo Client and on your [expo.io](https://expo.io) profile, submitting a standalone app to the Apple and Google stores is necessary to have a dedicated piece of real estate on your users' devices. Submitting to these stores carries stronger requirements and quality standards than sharing a toy project with a few friends, because it makes your app available through a much wider distribution platform. + +**Disclaimer:** Especially in the case of Apple, review guidelines and rules change all the time, and Apple's enforcement of various rules tends to be finicky and inconsistent. We can't guarantee that your particular project will be accepted by either platform, and you are ultimately responsible for your app's behavior. However, Expo apps are native apps and behave just like any other apps, so if you've created something awesome, you should have nothing to worry about! + +## Make sure your app works on many form factors + +It's a good idea to test your app on a device or simulator with a small screen (e.g. an iPhone SE) as well as a large screen (e.g. an iPhone X). Ensure your components render the way you expect, no buttons are blocked, and all text fields are accessible. + +Try your app on tablets in addition to handsets. Even if you have `ios.supportsTablet: false` configured, your app will still render at phone resolution on iPads and must be usable. + +## Make app loading seamless + +- Add a [splash screen](../../guides/splash-screens/), the very first thing your users see after they select your app. +- Use [AppLoading](../../sdk/app-loading/) to ensure your interface is ready before the user sees it. +- [Preload and cache your assets](../../guides/preloading-and-caching-assets/) so your app loads quickly, even with a poor internet connection. + +## Play nicely with the system UI + +- Configure the [status bar](../../guides/configuring-statusbar/) so it doesn't clash with your interface. +- Use [native gestures](../../sdk/gesture-handler/) whenever possible. +- Use interface elements that make sense on the device. For example, see the [iOS Human Interface Guidelines](https://developer.apple.com/ios/human-interface-guidelines/overview/themes/). + +## Tailor your app metadata + +- Add a great [icon](../../guides/app-icons/). Icon requirements between iOS and Android differ and are fairly strict, so be sure and familiarize yourself with that guide. +- Customize your [primaryColor](../../workflow/configuration/#primarycolor). +- Make sure your app has a valid iOS [Bundle Identifier](../../workflow/configuration/#bundleidentifier) and [Android Package](../../workflow/configuration/#package). Take care in choosing these, as you will not be able to change them later. +- Use [versionCode](../../workflow/configuration/#versioncode) and [buildNumber](../../workflow/configuration/#buildnumber) to distinguish different binaries of your app. + +## Privacy Policy + +- Starting October 3, 2018, all new iOS apps and app updates will be required to have a privacy policy in order to pass the App Store Review Guidelines. +- Additionally, a number of developers have reported warnings from Google if their app does not have a privacy policy, since by default all Expo apps contain code for requesting the Android Advertising ID. Though this code may not be executed depending on which Expo APIs you use, we still recommend that all apps on the Google Play Store include a privacy policy as well. + +## iOS-specific guidelines + +- All apps in the iTunes Store must abide by the [App Store Review Guidelines](https://developer.apple.com/app-store/review/guidelines/). +- Apple will ask you whether your app uses the IDFA. Because Expo depends on Segment Analytics, the answer is yes, and you'll need to check a couple boxes on the Apple submission form. See [Segment's Guide](https://segment.com/docs/sources/mobile/ios/quickstart/#step-5-submitting-to-the-app-store) for which specific boxes to fill in. + +## Common App Rejections + +- It's helpful to glance over [Common App Rejections](https://developer.apple.com/app-store/review/rejections/). +- Binaries can get rejected for having poorly formatted icons, so double check the [App Icon guide](../../guides/app-icons/). +- Apple can reject your app if elements don't render properly on an iPad, even if your app doesn't target the iPad form factor. Be sure and test your app on an iPad (or iPad simulator). +- Occasionally people get a message from Apple which mentions an IPv6 network. Typically this is just Apple's way of informing you what kind of network they tested on, and the actual "IPv6" detail is a red herring. All of Expo's iOS code uses `NSURLSession`, which is IPv6-compatible. [More info](https://forums.expo.io/t/ios-standalone-rejected-at-review-because-of-ipv6/7062). + +## System permissions dialogs on iOS + +If your app asks for [system permissions](../../sdk/permissions/) from the user, e.g. to use the device's camera, or access photos, Apple requires an explanation for how your app makes use of that data. Expo will automatically provide a boilerplate reason for you, such as "Allow cool-app to access the camera." If you would like to provide more information, you can override these values using the [ios.infoPlist](../../workflow/configuration) key in `app.json`, for example: + +``` +"infoPlist": { + "NSCameraUsageDescription": "This app uses the camera to scan barcodes on event tickets." +}, +``` + +The full list of keys Expo provides by default can be seen [here](https://github.com/expo/expo/blob/master/exponent-view-template/ios/exponent-view-template/Supporting/Info.plist#L28-L41). Unlike with Android, on iOS it is not possible to filter the list of permissions an app may request at a native level. This means that by default, your app will ship with all of these default boilerplate strings embedded in the binary. You can provide any overrides you want in the `infoPlist` configuration. Because these strings are configured at the native level, they will only be published when you build a new binary with `expo build`. + +## Localizing system dialogs on iOS + +If your app uses a language besides English, you can optionally provide [localized](../../sdk/localization/) strings for the system dialogs. For example, in `app.json`, you can provide + +``` +"locales": { + "ru": "./languages/russian.json" +} +``` + +...where `russian.json` looks like: + +``` +{ + "NSContactsUsageDescription": "Hello Russian words" +} +``` diff --git a/docs/pages/versions/unversioned/distribution/building-standalone-apps.md b/docs/pages/versions/unversioned/distribution/building-standalone-apps.md new file mode 100644 index 00000000000000..f4dc3738139a4a --- /dev/null +++ b/docs/pages/versions/unversioned/distribution/building-standalone-apps.md @@ -0,0 +1,189 @@ +--- +title: Building Standalone Apps +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +The purpose of this guide is to help you create standalone binaries of your Expo app for iOS and +Android which can be submitted to the Apple App Store and Google Play Store. + +An Apple Developer account is needed to build an iOS standalone app, but a Google Play Developer +account is not needed to build the Android standalone app. If you'd like to submit to either app +store, you will need a developer account on that store. + +It's a good idea to read the best practices about [Deploying to App Stores](../app-stores/) to +ensure your app is in good shape to get accepted into the Apple and Google marketplaces. We can +generate builds for you, but it's up to you to make your app awesome. + +## 1. Install Expo CLI + +Expo CLI is the tool for developing and building Expo apps. Run `npm install -g expo-cli` to get it. + +If you haven't created an Expo account before, you'll be asked to create one when running the build command. + +**Windows users** must have WSL enabled. We recommend picking Ubuntu from the Windows Store. Be sure +to Launch Ubuntu at least once. After that, use an Admin powershell to run: +`Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux` + +## 2. Configure app.json + +```javascript + { + "expo": { + "name": "Your App Name", + "icon": "./path/to/your/app-icon.png", + "version": "1.0.0", + "slug": "your-app-slug", + "sdkVersion": "XX.0.0", + "ios": { + "bundleIdentifier": "com.yourcompany.yourappname" + }, + "android": { + "package": "com.yourcompany.yourappname" + } + } + } +``` + +* The iOS `bundleIdentifier` and Android `package` fields use reverse DNS notation, but don't have to be related to a domain. Replace `"com.yourcompany.yourappname"` with whatever makes sense for your app. +* You're probably not surprised that `name`, `icon` and `version` are required. +* `slug` is the url name that your app's JavaScript is published to. For example: `expo.io/@community/native-component-list`, where `community` is my username and `native-component-list` is the slug. +* The `sdkVersion` tells Expo what Expo runtime version to use, which corresponds to a React Native version. Although `"XX.0.0"` is listed in the example, you already have an `sdkVersion` in your app.json and should not change it except when you want to update to a new version of Expo. + +There are other options you might want to add to `app.json`. We have only covered what is +required. For example, some people like to configure their own build number, linking scheme, and +more. We highly recommend you read through [Configuration with app.json](../../workflow/configuration/) for the +full spec. This is also your last chance to double check our [recommendations](../app-stores/) +for App Store metadata. + +## 3. Start the build + +Run `expo build:android` or `expo build:ios`. If you don't already have a packager running for this +project, `exp` will start one for you. + +### If you choose to build for Android + +The first time you build the project you will be asked whether you'd like to upload a keystore or +have us handle it for you. If you don't know what a keystore is, you can have us generate one for you. Otherwise, +feel free to upload your own. + +If you choose to let Expo generate a keystore for you, we **strongly recommend** that you later run `expo fetch:android:keystore` +and backup your keystore to a safe location. Once you submit an app to the Google Play Store, all future updates to that app **must** +be signed with the same keystore to be accepted by Google. If, for any reason, you delete your project or clear your credentials +in the future, you will not be able to submit any updates to your app if you have not backed up your keystore. + +```bash +[exp] No currently active or previous builds for this project. + +Would you like to upload a keystore or have us generate one for you? +If you don't know what this means, let us handle it! :) + + 1) Let Expo handle the process! + 2) I want to upload my own keystore! +``` + +> **Note:** If you choose the first option and later decide to upload your own keystore, we currently offer an option to clear your current Android keystore from our build servers by running `expo build:android --clear-credentials.` **This is irreversible, so only run this command if you know what you are doing!** You can download a backup copy of the keystore by running `expo fetch:android:keystore`. If you do not have a local copy of your keystore , you will be unable to publish new versions of your app to the Play Store. Your only option would be to generate a new keystore and re-upload your application as a new application. You can learn more about how code signing and keystores work [in the Android documentation](https://developer.android.com/studio/publish/app-signing.html). + +### If you choose to build for iOS + +You are given a choice of letting the `exp` client create the +necessary credentials for you, while still having a chance to provide +your own overrides. Your Apple ID and password is used locally and +never saved on Expo's servers. + +```bash +[exp] Making sure project is set up correctly... +[exp] Your project looks good! +[exp] Checking if current build exists... + +[exp] No currently active or previous builds for this project. +? How would you like to upload your credentials? + (Use arrow keys) +❯ Expo handles all credentials, you can still provide overrides + I will provide all the credentials and files needed, Expo does no validation +``` + +We ask you if you'd like us to handle your distribution certificate or +use your own. Similar to the Android keystore, if you don't know what +a distribution certificate is, just let us handle it for you. If you +do need to upload your own certificates, we recommend following +[this excellent guide on making a p12file](https://calvium.com/how-to-make-a-p12-file/). +**Note:** this guide recommends leaving the p12's password blank, but a p12 password +is required to upload your own certificate to Expo's service. Please enter a password +when prompted. + +> **Note:** The Expo build service supports both normal App Store distribution as well as enterprise +> distribution. To use the latter, you must be a member of the ["Apple Developer Enterprise +> Program"](https://developer.apple.com/programs/enterprise/). Only normal Apple developer accounts +> can build apps that can be submitted to the Apple App Store, and only enterprise developer +> accounts can build apps that can be distributed using enterprise distribution methods. When you +> call `expo build:ios`, use the `--apple-enterprise-account` flag. At this time, the standalone app +> builder does not support "ad hoc" distribution certificates or provisioning profiles. + +## 4. Wait for it to finish building + +When one of our building machines will be free, it'll start building your app. You can check how long you'll wait on [Turtle status](https://expo.io/turtle-status) site. We'll print a url you can visit (such as `expo.io/builds/some-unique-id`) to watch your build logs. Alternatively, you can check up on it by running `expo build:status`. When it's done, you'll see the url of a `.apk` (Android) or `.ipa` (iOS) file -- this is your app. Copy and paste the link into your browser to download the file. + +If you would like to, we can also call your webhook once the build has finished. You can set up a webhook for you project using `expo webhooks:set --event build --url ` command. You will be asked to type a webhook secret. It has to be at least 16 characters long and it will be used to calculate the signature of the request body which we send as the value of the `Expo-Signature` HTTP header. You can use the signature to verify a webhook request is genuine. We promise you that we keep your secret securely encrypted in our database. + +We call your webhook using an HTTP POST request and we pass data in the request body. Expo sends your webhook with JSON object with following fields: +- `status` - a string specifying whether your build has finished successfully (can be either `finished` or `errored`) +- `id` - the unique ID of your build +- `artifactUrl` - the URL to the build artifact (we only include this field if the build is successful) + +Additionally, we send an `Expo-Signature` HTTP header with the hash signature of the payload. You can use this signature to verify the request is from Expo. The signature is a hex-encoded HMAC-SHA1 digest of the request body, using your webhook secret as the HMAC key. + +This is how you can implement your server: +```javascript +import crypto from 'crypto'; +import express from 'express'; +import bodyParser from 'body-parser'; +import safeCompare from 'safe-compare'; + +const app = express(); +app.use(bodyParser.text({ type: '*/*' })); +app.post('/webhook', (req, res) => { + const expoSignature = req.headers['expo-signature']; + // process.env.SECRET_WEBHOOK_KEY has to match value set with `expo webhooks:set ...` command + const hmac = crypto.createHmac('sha1', process.env.SECRET_WEBHOOK_KEY); + hmac.update(req.body); + const hash = `sha1=${hmac.digest('hex')}`; + if (!safeCompare(expoSignature, hash)) { + res.status(500).send("Signatures didn't match!"); + } else { + // do sth here + res.send('OK!'); + } +}); +app.listen(8080, () => console.log('Listening on port 8080')); +``` + +You can always change your webhook URL and/or webhook secret using the same command you used to set up the webhook for the first time. To see what your webhook is currently set to, you can use `expo webhooks:show` command. If you would like us to stop sending requests to your webhook, simply run `expo webhooks:clear` in your project. + +> **Note:** We enable bitcode for iOS, so the `.ipa` files for iOS are much larger than the eventual App Store download available to your users. For more information, see [App Thinning](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/AppDistributionGuide/AppThinning/AppThinning.html). + +## 5. Test it on your device or simulator + +* You can drag and drop the `.apk` into your Android emulator. This is the easiest way to test out that the build was successful. But it's not the most satisfying. +* **To run it on your Android device**, make sure you have the Android platform tools installed along with `adb`, then just run `adb install app-filename.apk` with [USB debugging enabled on your device](https://developer.android.com/studio/run/device.html#device-developer-options) and the device plugged in. +* **To run it on your iOS Simulator**, first build your expo project with the simulator flag by running `expo build:ios -t simulator`, then download the tarball with the link given upon completion when running `expo build:status`. Unpack the tar.gz by running `tar -xvzf your-app.tar.gz`. Then you can run it by starting an iOS Simulator instance, then running `xcrun simctl install booted ` and `xcrun simctl launch booted `. +* **To test a device build with Apple TestFlight**, download the .ipa file to your local machine. You are ready to upload your app to TestFlight. Within TestFlight, click the plus icon and create a New App. Make sure your `bundleIdentifier` matches what you've placed in `app.json`. + +> **Note:** You will not see your build here just yet! You will need to use Xcode or Application Loader to upload your IPA first. Once you do that, you can check the status of your build under `Activity`. Processing an app can take 10-15 minutes before it shows up under available builds. + +## 6. Submit it to the appropriate store + +We don't automate this step (yet), but at this point you should be able to follow the Apple and Google documentation to submit your standalone binary to each respective store. For more info on how to polish your app and ensure it is accepted to the Apple and Google marketplaces, read the guide on [Deploying to App Stores](../app-stores/). + +## 7. Update your app + +For the most part, when you want to update your app, just Publish again from Expo CLI. Your users will download the new JS the next time they open the app. To ensure your users have a seamless experience downloading JS updates, you may want to enable [background JS downloads](../../guides/offline-support/). However, there are a couple reasons why you might want to rebuild and resubmit the native binaries: + +* If you want to change native metadata like the app's name or icon +* If you upgrade to a newer `sdkVersion` of your app (which requires new native code) + +To keep track of this, you can also update the binary's [versionCode](../../workflow/configuration/#versioncode) and [buildNumber](../../workflow/configuration/#buildnumber). It is a good idea to glance through the [app.json documentation](../../workflow/configuration/) to get an idea of all the properties you can change, e.g. the icons, deep linking url scheme, handset/tablet support, and a lot more. + +If you run into problems during this process, we're more than happy to help out! [Join our Forums](https://forums.expo.io/) and let us know if you have any questions. diff --git a/docs/pages/versions/unversioned/distribution/hosting-your-app.md b/docs/pages/versions/unversioned/distribution/hosting-your-app.md new file mode 100644 index 00000000000000..fe51065d04c0da --- /dev/null +++ b/docs/pages/versions/unversioned/distribution/hosting-your-app.md @@ -0,0 +1,124 @@ +--- +title: Hosting An App on Your Servers +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +> **WARNING:** This feature is in beta. + +Normally, when over-the-air (OTA) updates are enabled, your app will fetch JS bundles and assets from Expo’s CDN. However, there will be situations when you will want to host your JS bundles and assets on your own servers. For example, OTA updates are slow or unusable in countries that have blocked Expo’s CDN providers on AWS and Google Cloud. In these cases, you can host your app on your own servers to better suit your use case. + +For simplicity, the rest of this article will refer to hosting an app for the Android platform, but you could swap out Android for iOS at any point and everything would still be true. + +## Export app + +First, you’ll need to export all the static files of your app so they can be served from your CDN. To do this, run `expo export --public-url ` in your project directory and it will output all your app’s static files to a directory named `dist`. In this guide, we will use `https://quinlanj.github.io/self-host` as our example server endpoint. Asset and bundle files are named by the md5 hash of their content. Your output directory should look something like this now: +``` +. +├── android-index.json +├── ios-index.json +├── assets +│ └── 1eccbc4c41d49fd81840aef3eaabe862 +└── bundles + ├── android-01ee6e3ab3e8c16a4d926c91808d5320.js + └── ios-ee8206cc754d3f7aa9123b7f909d94ea.js +``` + +## Hosting your static files + +Once you've exported your app's static files, you can host the contents on your own server. For example, in your `dist` output directory, an easy way to host your own files is to push the contents to Github. You can enable [Github Pages](https://pages.github.com/) to make your app available at a base URL like https://username.github.io/project-name. To host your files on Github, you'd do something like this: + +``` +# run this from your project directory +expo export --public-url https://quinlanj.github.io/self-host + +# commit output directory contents to your repo +cd dist +git init && git remote add origin git@github.com:quinlanj/self-host.git +git add * && git commit -m "Update my app with this JS bundle" +git push origin master +``` + +To setup a QR code to view your hosted app, or if you want to host your files locally, follow the instructions below in the 'Loading QR Code/URL in Development' section. + +## Build standalone app + +In order to configure your standalone binary to pull OTA updates from your server, you’ll need to define the URL where you will host your `index.json` file. Pass the URL to your hosted `index.json` file to the `expo build` command. + +For iOS builds, run the following commands from your terminal: +`expo build:ios --public-url `, where the `public-url` option will be something like https://quinlanj.github.io/self-host/ios-index.json + +For Android builds, run the following commands from your terminal: +`expo build:android --public-url `, where the `public-url` option will be something like https://quinlanj.github.io/self-host/android-index.json + + +## Loading QR Code/URL in Development + +You can also load an app hosted on your own servers as a QR code/URL into the Expo mobile client for development purposes. + +### QR code: +The URI you’ll use to convert to QR code will be deeplinked using the `exps`/`exp` protocol. Both `exps` and `exp` deeplink into the mobile app and perform a request using HTTPS and HTTP respectively. You can create your own QR code using an online QR code generator from the input URI. + +#### Here’s an example of how you’d do this with a remote server: + +URI: `exps://quinlanj.github.io/self-host/android-index.json` + +QR code: Generate the URI from a website like https://www.qr-code-generator.com/ + +#### Here’s an example of how you’d do this from localhost: + +Run `expo export` in dev mode and then start a simple HTTP server in your output directory: + +``` +# Find your local IP address with `ipconfig getifaddr en0` +# export static app files +expo export --public-url http://`ipconfig getifaddr en0`:8000 --dev + +# cd into your output directory +cd dist + +# run a simple http server from output directory +python -m SimpleHTTPServer 8000 +``` + +URI: `exp://192.xxx.xxx.xxx:8000/android-index.json` (find your local IP with a command like `ipconfig getifaddr en0`) + +QR code: Generate a QR code using your URI from a website like https://www.qr-code-generator.com/ + +### URL +If you are loading in your app into the expo client by passing in a URL string, you will need to pass in an URL pointing to your json file. + +Here is an example URL from a remote server: [https://quinlanj.github.io/self-host/android-index.json](https://quinlanj.github.io/self-host/android-index.json) + +Here is an example URL from localhost: `http://localhost:8000/android-index.json` + +## Advanced Topics +### Debugging +When we bundle your app, minification is always enabled. In order to see the original source code of your app for debugging purposes, you can generate source maps. Here is an example workflow: + +1. Run `expo export --dump-sourcemap`. This will also export your bundle sourcemaps in the `bundles` directory. +2. A `debug.html` file will also be created at the root of your output directory. +3. In Chrome, open up `debug.html` and navigate to the `Source` tab. In the left tab there should be a resource explorer with a red folder containing the reconstructed source code from your bundle. + +![Debugging Source Code](/static/images/host-your-app-debug.png) + +### Multimanifests +As new Expo SDK versions are released, you may want to serve multiple versions of your app from your server endpoint. For example, if you first released your app with SDK 29 and later upgraded to SDK 30, you'd want users with your old standalone binary to receive the SDK 29 version, and those with the new standalone binary to receive the SDK 30 version. +In order to do this, you can run `expo export` with some merge flags to combine previously exported apps into a single multiversion app which you can serve from your servers. + +Here is an example workflow: +1. Release your app with previous Expo SDKs. For example, when you released SDK 29, you can run `expo export --output-dir sdk29`. This exports the current version of the app (SDK 29) to a directory named `sdk29`. + +2. Update your app and include previous Expo SDK versions. For example, if you've previously released SDK 28 and 29 versions of your app, you can include them when you release an SDK 30 version by running `expo export --merge-src-dir sdk29 --merge-src-dir sdk28`. Alternatively, you could also compress and host the directories and run `expo export --merge-src-url https://examplesite.com/sdk29.tar.gz --merge-src-url https://examplesite.com/sdk28.tar.gz`. This creates a multiversion app in the `dist` output directory. The `asset` and `bundle` folders contain everything that the source directories had, and the `index.json` file contains an array of the individual `index.json` files found in the source directories. + +### Asset Hosting +By default, all assets are hosted from an `assets` path resolving from your `public-url` (e.g. https://quinlanj.github.io/self-host/assets). You can override this behavior in the `assetUrlOverride` field of your `android-index.json`. All relative URL's will be resolved from the `public-url`. + +### Special fields +Most of the fields in the `index.json` files are the same as in `app.json`. Here are some fields that are notable in `index.json`: +- `revisionId`, `commitTime`, `publishedTime`: These fields are generated by `expo export` and used to determine whether or not an OTA update should occur. +- `bundleUrl`: This points to the path where the app's bundles are hosted. They are also used to determined whether or not an OTA update should occur. +- `slug`: This should not be changed. Your app is namespaced by `slug`, and changing this field will result in undefined behavior in the Expo SDK components such as `Filesystem`. +- `assetUrlOverride`: The path which assets are hosted from. It is by default `./assets`, which is resolved relative to the base `public-url` value you initially passed in. diff --git a/docs/pages/versions/unversioned/distribution/index.md b/docs/pages/versions/unversioned/distribution/index.md new file mode 100644 index 00000000000000..108439bb8be0a4 --- /dev/null +++ b/docs/pages/versions/unversioned/distribution/index.md @@ -0,0 +1,13 @@ +--- +title: Distributing Your App +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Distributing your app to your users is a critical process in the development of any product. This documentation will cover topics related to app distribution, such as how to: + +- [Create native builds](building-standalone-apps/) you can submit to the Apple App Store and Google Play Store +- Prepare your app for [deployment to the App Store and Play Store](app-stores/) and avoid common rejections. +- Manage different [release environments](release-channels/) for your app diff --git a/docs/pages/versions/unversioned/distribution/release-channels.md b/docs/pages/versions/unversioned/distribution/release-channels.md new file mode 100644 index 00000000000000..e9e85f06e00ff4 --- /dev/null +++ b/docs/pages/versions/unversioned/distribution/release-channels.md @@ -0,0 +1,77 @@ +--- +title: Release Channels +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +## Introduction + +Use release channels in Expo to send out different versions of your application to your users by giving them a URL or configuring your standalone app. You should use release channels if: +- You have an app in production and need a testing environment. +- You have multiple versions of your app. + +## Publish with Channels + +Publish your release by running: + +`expo publish --release-channel ` + +with the `exp` cli. Your users can see this release in the Expo client app with a parameterized URL `https://exp.host/@username/yourApp?release-channel=`. If you do not specify a channel, you will publish to the `default` channel. + +## Build with Channels + +Build your standalone app by running + +`expo build:ios --release-channel ` + +`expo build:android --release-channel ` + +with the `exp` cli. The binary produced will only pull releases published under the specified channel. If you do not specify a channel, your binary will pull releases from the `default` channel. + +## Access Channel from Code + +You can access the channel your release is published under with the `releaseChannel` field in the [manifest object](../../sdk/constants/#expoconstantsmanifest). + +> `Expo.Constants.manifest.releaseChannel` does NOT exist in dev mode. It does exist, however when you explicitly publish / build with it. + +## Example Workflow + +Consider a situation where you have a Staging stack for testing on Expo Client, and a Production stack for pushing through TestFlight, then promoting to the AppStore. + +On the staging stack, run `expo publish --release-channel staging`. Your test users can see the staging version of your app by specifying the channel in the query parameter of the URL (ie)`https://exp.host/@username/yourApp?release-channel=staging`, then opening the URL in their web browser, and finally scanning the QR code with the Expo client. Alternatively, they can open that URL directly on their mobile device. + +On the production stack, release v1 of your app by running `expo publish --release-channel prod-v1`. You can build this version of your app into a standalone ipa by running `expo build:ios --release-channel prod-v1`. You can push updates to your app by publishing to the `prod-v1` channel. The standalone app will update with the most recent compatible version of your app on the `prod-v1` channel. + +If you have a new version that you dont want v1 users getting, release v2 of your app by running `expo publish --release-channel prod-v2` and building it with `expo build:ios --release-channel prod-v2`. Users with the `prod-v2` ipa will only be pulling releases from that channel. + +You can continue updating v1 of your app with `expo publish --release-channel prod-v1`, and users who havent updated to the latest `prod-v2` ipa in the Apple App Store will continue receiving the latest `prod-v1` releases. + +## Using Release Channels with ExpoKit + +Since `expo build` does not apply to ExpoKit projects, you can edit the native project's release channel manually by modifying the `releaseChannel` key in [EXShell.plist](https://github.com/expo/expo/blob/master/ios/Exponent/Supporting/EXShell.plist) (iOS) or the `RELEASE_CHANNEL` value in [AppConstants.java](https://github.com/expo/expo/blob/master/android/app/src/main/java/host/exp/exponent/generated/AppConstants.java) (Android). + +## Using Release Channels for Environment Variable Configuration + +Environment variables don't exist explicitly, but you can utilize release channels to make that happen! + +Say you have a workflow of releasing builds like this: + +- `expo publish --release-channel prod-v1` +- `expo publish --release-channel prod-v2` +- `expo publish --release-channel prod-v3` + +- `expo publish --release-channel staging-v1` +- `expo publish --release-channel staging-v2` + + +You can create a function that looks for the specific release and sets the correct variable. + +```javascript +function getApiUrl(releaseChannel) { + if (releaseChannel === undefined) return App.apiUrl.dev // since releaseChannels are undefined in dev, return your default. + if (releaseChannel.indexOf('prod') !== -1) return App.apiUrl.prod // this would pick up prod-v1, prod-v2, prod-v3 + if (releaseChannel.indexOf('staging') !== -1) return App.apiUrl.staging // return staging environment variables +} +``` diff --git a/docs/pages/versions/unversioned/distribution/turtle-cli.md b/docs/pages/versions/unversioned/distribution/turtle-cli.md new file mode 100644 index 00000000000000..307b0014135a21 --- /dev/null +++ b/docs/pages/versions/unversioned/distribution/turtle-cli.md @@ -0,0 +1,141 @@ +--- +title: Building Standalone Apps on Your CI +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +> **NOTE:** macOS is required to build standalone iOS apps. + +This guide describes an advanced feature of Expo. In most cases you can build +standalone Expo apps using Expo's build services as described in the guide +on [Building Standalone Apps](../building-standalone-apps/). + +If you prefer to not rely on our builders stability and you don't like waiting +in the queue to get your standalone app build then you can build your Expo +project on your own. The only thing you need is Turtle CLI. Turtle CLI is +a command line interface for building Expo standalone apps. You can use it +both on your CI and your private computer. + +## Install Turtle CLI + +### Prerequisites + +You'll need to have these things installed: +- bash +- Node.js (version 8 or newer) - [download the latest version of Node.js](https://nodejs.org/en/). + +#### For Android builds + +- [Java Development Kit (version 8)](https://jdk.java.net/) +- gulp-cli (run `npm install -g gulp-cli` to get it) + +#### For iOS builds + +- macOS +- Xcode (version 9.4.1 or newer) - make sure you have run it at least once +and you have agreed to the license agreements. Alternatively you can run `sudo xcodebuild -license`. +- fastlane - [see how to install it](https://docs.fastlane.tools/getting-started/ios/setup/#installing-fastlane) + +### Turtle CLI + +Install Turtle CLI by running: + +```bash +$ npm install -g turtle-cli +``` + +Then run `turtle setup:ios` and/or `turtle setup:android` to verify everything +is installed correctly. This step is optional and is also performed during +the first run of the Turtle CLI. Please note that the Android setup command +downloads, installs, and configures the appropriate versions of the Android SDK +and NDK. + +If you would like to make the first build even faster, you can supply the Expo +SDK version to the setup command like so: `turtle setup:ios --sdk-version 30.0.0`. +This tells Turtle CLI to download additional Expo-related dependencies for +the given SDK version. + +All Expo-related dependencies will be installed in a directory named `.turtle` +within your home directory. This directory may be removed safely if you ever +need to free up some disk space. + +## Publish your project + +In order to build your standalone Expo app, you first need to have successfully +published your project. See the guide on [how to publish your project](../../workflow/publishing/) +with Expo CLI or [how to host an app on your servers](../hosting-your-app/). + +## Start the build + +If you choose to publish your app to Expo servers, you must have an Expo +developer account and supply your credentials to the `turtle-cli`. +The recommended approach is to define two environment variables called +`EXPO_USERNAME` and `EXPO_PASSWORD` with your credentials, though you may also +pass these values to the build command from the command line. We recommending +using the environment variables to help keep your credentials out of your +terminal history or CI logs. + +### Building for Android + +Before starting the build, prepare the following things: + +- Keystore +- Keystore alias +- Keystore password and key password + +To learn how to generate those, see the guide on [Building Standalone Apps](../building-standalone-apps/) +first. + +Set the `EXPO_ANDROID_KEYSTORE_PASSWORD` and `EXPO_ANDROID_KEY_PASSWORD` +environment variables with the values of the keystore password and key password, +respectively. + +Then, start the standalone app build: +```bash +$ turtle build:android \\ + --keystore-path /path/to/your/keystore.jks \\ + --keystore-alias PUT_KEYSTORE_ALIAS_HERE +``` + +If the build finishes successfully you will find the path to the build artifact +in the last line of the logs. + +If you want to print the list of all available command arguments, +please run `turtle build:android --help`. + +### Building for iOS + +Prepare the following unless you're building only for the iOS simulator: + +- Apple Team ID - (a 10-character string like "Q2DBWS92CA") +- Distribution Certificate .p12 file *(+ password)* +- Provisioning Profile + +To learn how to generate those, see the guide +on [Building Standalone Apps](../building-standalone-apps/) first. + +Set the `EXPO_IOS_DIST_P12_PASSWORD` environment variable with the value of +the Distribution Certificate password. + +Then, start the standalone app build: +```bash +$ turtle build:ios \\ + --team-id YOUR_TEAM_ID \\ + --dist-p12-path /path/to/your/dist/cert.p12 \\ + --provisioning-profile-path /path/to/your/provisioning/profile.mobileprovision +``` + +If the build finishes successfully you will find the path to the build artifact +in the last line of the logs. + +If you want to print the list of all available command arguments, +please run `turtle build:ios --help`. + + +## CI configuration file examples + +See [expo/turtle-cli-example](https://github.com/expo/turtle-cli-example) repository +for examples of how to use Turtle CLI with popular CI services (i.e. [CircleCI](#circleci) +and [Travis CI](#travis-ci)). diff --git a/docs/pages/versions/unversioned/distribution/uploading-apps.md b/docs/pages/versions/unversioned/distribution/uploading-apps.md new file mode 100644 index 00000000000000..829431b0394650 --- /dev/null +++ b/docs/pages/versions/unversioned/distribution/uploading-apps.md @@ -0,0 +1,90 @@ +--- +title: Uploading Apps to the Apple App Store and Google Play +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +**Disclaimer:** This feature works properly only on macOS. + +This guide will help you upload your Expo standalone apps to Apple TestFlight and to Google Play. +You'll need a paid developer account for each platform for which you wish to upload and publish an app. You can create an Apple Developer account on [Apple's developer site](https://developer.apple.com/account/) and a Google Play Developer account on the [Google Play Console sign-up page](https://play.google.com/apps/publish/signup/). + +## 1. Build a standalone app + +To learn how to build native binaries, see [Building Standalone Apps](../building-standalone-apps/) or [Building Standalone Apps on Your CI](../turtle-cli). + +## 2. Start the upload + +To upload the previously built standalone app to the appropriate app store, you simply run `expo upload:android` or `expo upload:ios`. However, you have a few options for choosing which app binary you want to upload (remember to choose one at the time): +- `--latest` - chosen by default, uploads the latest build for the given platform found on the Expo servers +- `--id ` - uploads a build with the given ID +- `--path ` - uploads a build from the local file system + +## 2.1. If you choose to upload your Android app to Google Play + +**Important:** You have to create a Google Service Account and download its JSON private key. After that, you'll have to create an app on the [Google Play Console](https://play.google.com/apps/publish/) and upload your app manually at least once. + +#### Creating a Google Service Account + +1. Open the [Google Play Console](https://play.google.com/apps/publish/). +2. Click the **Settings** menu entry, followed by **API access**. +3. Click the **CREATE SERVICE ACCOUNT** button. If you see a message saying API access is not enabled for your account, you must first link your Google Play developer account with a Google Developer Project. On this page, either link it to an existing project if you have one, or click **CREATE NEW PROJECT** to link with a new one. +4. Follow the **Google API Console** link in the dialog + 1. Click the **CREATE SERVICE ACCOUNT** button + 2. Enter the name of this service account in the field titled "Service account name". We recommend a name that will make it easy for you to remember that it is for your Google Play Console account. Also, enter the service account ID and description of your choice. + 3. Click **Select a role** and choose **Service Accounts > ServiceAccount User** + 4. Check the **Furnish a new private key** checkbox + 5. Make sure the "Key type" field is set to **JSON** + 6. Click **SAVE** to close the dialog + 7. Make a note of the filename of the JSON file downloaded to your computer. You'll need this to upload your app later. Be sure to keep this JSON file secure, as it provides API access to your Google Play developer account. +5. Return to the **API access** page on the **Google Play Console** and ensure it shows your new service account. +6. Click on **Grant Access** for the newly added service account +7. Choose **Release Manager** from the newly added service account +8. Click **ADD USER** to close the dialog + +#### Manually uploading your app for the first time + +Before using `expo-cli` for uploading your standalone app builds, you have to upload your app manually at least once. [See here for the instructions on how to do it.](https://support.google.com/googleplay/android-developer/answer/113469) + +#### Using expo-cli to upload the further builds of your app + +After these steps, you can make use of `expo-cli` to upload your further app builds to Google Play. + +To upload your Android app to Google Play, run `expo upload:android`. You can set following options when uploading an Android standalone app: +- `--key ` **(required)** - path to the JSON key used to authenticate with the Google Play Store (created in the previous steps) +- `--track ` - the track of the application to use, choose from: production, beta, alpha, internal, rollout (default: internal) + +## 2.2. If you choose to upload your iOS app to TestFlight + +### Using expo-cli + +To upload your iOS app to TestFlight, run `expo upload:ios`. You can set following options when uploading an iOS standalone app: +- `--apple-id ` **(required)** - your Apple ID login. Alternatively you can set the `EXPO_APPLE_ID` environment variable. +- `--apple-id-password ` **(required)** - your Apple ID password. Alternatively you can set the `EXPO_APPLE_ID_PASSWORD` environment variable. +- `--app-name ` - your app display name, will be used to name an app on App Store Connect +- `--sku ` - a unique ID for your app that is not visible on the App Store, will be generated unless provided +- `--language ` - primary language (e.g. English, German; run `expo upload:ios --help` to see the list of available languages) (default: English) + +### Manually uploading your app + +In order to see your app on Testflight, you will first need to submit your .IPA file to Apple using Application loader. In order to do this, there are a few prequisite steps which you may not have followed previously if this is your first app submission to Apple: + +1. Make sure you have logged into iTunes connect at least once with your Apple ID and accepted the terms. +2. Login to https://appleid.apple.com +3. Generate an app specific password by going to Accounts > Manage > Generate App Specific Password. Make a note of this password as it will be needed later. +4. Start XCode but do not load any project +5. From the XCode menu in the menu bar, select 'Open Developer Tool' and then 'Application Loader' +6. Once Application Loader launches, login with your Apple ID and the app specific password generated in step 3 +7. Follow the steps to agree to the necessary terms. +8. Once you have agreed to all terms, double-click on the light-grey panel in the center (above the words 'Deliver Your App'). +9. Follow the steps to upload your IPA to Apple. + +You can check the status of your app submission to TestFlight in App Store Connect (http://appstoreconnect.apple.com): + +1. Login to http://appstoreconnect.apple.com with your Apple ID and regular password (NOT your app specific password) +2. Select 'My Apps' and you should see your app listed. +3. Click 'TestFlight' from the menu bar at the top. +4. This will show your current app builds that are available for testing. +5. In order to test the app on your device, you will need to install the TestFlight iOS app from the App Store, and sign in using your Apple ID. diff --git a/docs/pages/versions/unversioned/expokit/advanced-expokit-topics.md b/docs/pages/versions/unversioned/expokit/advanced-expokit-topics.md new file mode 100644 index 00000000000000..adc782d6e94bec --- /dev/null +++ b/docs/pages/versions/unversioned/expokit/advanced-expokit-topics.md @@ -0,0 +1,79 @@ +--- +title: Advanced ExpoKit Topics +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +This guide goes deeper into a few [ExpoKit](../expokit/) topics that aren't critical +right out of the box, but that you may encounter down the road. If you're not familiar with +ExpoKit, you might want to read [the ExpoKit guide](../expokit/) first. + +## Un-ejecting + +It is possible to manually "un-eject" your project, for example if you want to return to a JS-only state, or if you want to repeatedly eject for testing purposes. Since your project won't be ejected any more, you will no longer be able to use custom native code. + +> **Warning:** The following instructions will permanently remove the native iOS and Android code from your project, including any changes you've made. We strongly recommend committing your changes to version control before trying this. + +To un-eject: + +- Delete the `ios` and `android` directories from your project. +- Delete the `isDetached` and `detach` keys from your project's `app.json`. + +You can now use your project like a normal Expo project (with no ExpoKit). + +## Verifying Bundles (iOS only) + +When we serve your JS over-the-air to your ExpoKit project, we include a signature so that +your project can verify that the JS actually came from our servers. + +By default, projects that use ExpoKit have this feature disabled on iOS and enabled on +Android. We encourage you to enable it on iOS so that your code is verified for all of your +users. + +To enable code verification in your native project with ExpoKit: + +- Fulfill one of these two requirements (you only need one): + + - Use a non-wildcard bundle identifier when provisioning the app (recommended) + - Enable **Keychain Sharing** in your Xcode project settings under **Capabilities**. (faster to + set up) + +- In `ios/your-project/Supporting/EXShell.plist`, set `isManifestVerificationBypassed` to + `NO` (or delete this key entirely). + +## Configuring the JS URL + +In development, your ExpoKit project will request your local build from Expo CLI. You can see this configuration in `EXBuildConstants.plist` (iOS) or `ExponentBuildConstants` (Android). You shouldn't need to edit it, because it's written automatically when you serve the project. + +In production, your ExpoKit project will request your published JS bundle. This is configured in `EXShell.plist` (iOS) and `MainActivity.java` (Android). If you want to specify custom behavior in iOS, you can also set the `[ExpoKit sharedInstance].publishedManifestUrlOverride` property. + +## Changing the Deep Link Scheme + +If you do not have a `scheme` specified in app.json at the time of ejecting, Expo will automatically generate a random one for you. If you'd like to switch to a different scheme after ejecting, there are a few places where you need to find an occurrence of your old scheme and replace it with the new one: + +1. `app.json` (the `"scheme"` field) +2. `ios//Supporting/Info.plist` (under the first occurrence of`CFBundleURLSchemes`) +3. `android/app/src/main/AndroidManifest.xml` (in a line that looks like ``, under `MainActivity`, or `LauncherActivity` for older projects) +4. `android/app/src/main/java/host/exp/exponent/generated/AppConstants.java` (the `SHELL_APP_SCHEME` variable) + +## Enabling Optional Expo Modules on iOS + +To enable FaceDetector, ARKit, or Payments in your iOS app, see [Universal Modules and ExpoKit](../universal-modules-and-expokit/). + +## Using DocumentPicker + +In iOS Expokit projects, the DocumentPicker module requires the iCloud entitlement to work properly. If your app doesn't have it already, you can add it by opening the project in Xcode and following these steps: + +- In the project go to the `Capabilities` tab. +- Set the iCloud switch to on. +- Check the `iCloud Documents` checkbox. + +If everything worked properly your screen should look like this: + +![](/static/images/icloud-entitlement.png) + +## Using Google Maps + +If you integrate Google Maps to your ExpoKit app with the MapView component, you may need to follow additional instructions to provide your Google Maps API key. See the [MapView docs](../../sdk/map-view/). diff --git a/docs/pages/versions/unversioned/expokit/eject.md b/docs/pages/versions/unversioned/expokit/eject.md new file mode 100644 index 00000000000000..d793c111e0dac1 --- /dev/null +++ b/docs/pages/versions/unversioned/expokit/eject.md @@ -0,0 +1,88 @@ +--- +title: Ejecting to ExpoKit +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +ExpoKit is an Objective-C and Java library that allows you to use the Expo platform and your existing Expo project as part of a larger standard native project -- one that you would normally create using Xcode, Android Studio, or `react-native init`. + +## What is this for? + +If you created an Expo project and you want a way to add custom native modules, this guide will explain how to use ExpoKit for that purpose. + +Normally, Expo apps are written in pure JS and never "drop down" to the native iOS or Android layer. This is core to the Expo philosophy and it's part of what makes Expo fast and powerful to use. + +However, there are some cases where advanced developers need native capabilities outside of what Expo offers out-of-the-box. The most common situation is when a project requires a specific Native Module which is not supported by React Native Core or the Expo SDK. + +In this case, Expo allows you to _eject_ your pure-JS project from the Expo iOS/Android clients, providing you with native projects that can be opened and built with Xcode and Android Studio. Those projects will have dependencies on ExpoKit, so everything you already built will keep working as it did before. + +We call this "ejecting" because you still depend on the Expo SDK, but your project no longer lives inside the standard Expo client. You control the native projects, including configuring and building them yourself. + +## Should I eject to ExpoKit? + +### You might want to eject if: + +- Your Expo project needs a native module that Expo doesn't currently support. We're always expanding the [Expo SDK](../../sdk/), so we hope this is never the case. But it happens, especially if your app has very specific and uncommon native demands. + +### You should not eject if: + +- All you need is to distribute your app in the iTunes Store or Google Play. Expo can [build binaries for you](../../distribution/building-standalone-apps/) in that case. If you eject, we can't automatically build for you any more. +- You are uncomfortable writing native code. Ejected apps will require you to manage Xcode and Android Studio projects. +- You enjoy the painless React Native upgrades that come with Expo. After your app is ejected, breaking changes in React Native will affect your project differently, and you may need to figure them out for your particular situation. +- You require Expo's push notification services. After ejecting, since Expo no longer manages your push certificates, you'll need to manage your own push notification pipeline. +- You rely on asking for help in the Expo community. In your native Xcode and Android Studio projects, you may encounter questions which are no longer within the realm of Expo. + +## Instructions + +The following steps are for converting a pure-JS Expo project (such as one created with Expo CLI) +into a native iOS and Android project which depends on ExpoKit. + +After you eject, all your JS files will stay the same, but we'll additionally create `ios` and +`android` directories in your project folder. These will contain Xcode and Android Studio projects +respectively, and they'll have dependencies on React Native and on Expo's core SDK. + +You'll still be able to develop and test your project with Expo CLI, and you'll still be able to publish +your Expo JS code the same way. However, if you add native dependencies that aren't included +in Expo, other users won't be able to run those features of your app with the main Expo app. +You'll need to distribute the native project yourself. + +### 1. Install Expo CLI + +If you don't have it, run `npm install -g expo-cli` to get our command line library. + +If you haven't used Expo CLI with an Expo account before, the eject command will ask you to create one. + +### 2. Make sure you have the necessary configuration options in app.json + +Ejecting requires the same configuration options as building a standalone app. [Follow these instructions before continuing to the next step](../../distribution/building-standalone-apps/#2-configure-appjson). + +### 3. Eject + +From your project directory, run `expo eject`. This will download the required dependencies and +build native projects under the `ios` and `android` directories. + +### 4. Set up and Run your native project + +Congrats, you now have a native project with ExpoKit! Follow the directions under [Developing with ExpoKit](../expokit/) to get things set up and running. + +### 5. Make native changes + +You can do whatever you want in the Xcode and Android Studio projects. + +To add third-party native modules for React Native, non-Expo-specific instructions such as `react-native link` should be supported. [Read more details about changing native dependencies in your ExpoKit project](../expokit/#changing-native-dependencies). + +### 6. Distribute your app + +Publishing your JS from Expo CLI will still work. Users of your app will get the new JS on their +devices as soon as they reload their app; you don't need to rebuild your native code if it has +not changed. + +If you do make native changes, people who don't have your native code may encounter crashes if +they try to use features that depend on those changes. + +If you decide to distribute your app as an `ipa` or `apk`, it will automatically hit +your app's published URL instead of your development Expo CLI URL. Read [advanced details about your app's JS url](../advanced-expokit-topics/#configuring-the-js-url). + +In general, before taking your app all the way to production, it's a good idea to glance over the [Advanced ExpoKit Topics](../advanced-expokit-topics/) guide. diff --git a/docs/pages/versions/unversioned/expokit/expokit.md b/docs/pages/versions/unversioned/expokit/expokit.md new file mode 100644 index 00000000000000..51ba17ec0febc7 --- /dev/null +++ b/docs/pages/versions/unversioned/expokit/expokit.md @@ -0,0 +1,248 @@ +--- +title: Developing With ExpoKit +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +ExpoKit is an Objective-C and Java library that allows you to use the Expo platform with a +native iOS/Android project. + +## Before you read this guide + +To create an ExpoKit project: + +1. Create a pure-JS project with Expo CLI (also projects that were created with exp, XDE or create-react-native-app will work) +2. Then use [`expo eject`](../eject/) to add ExpoKit (choose the "ExpoKit" option). + +Make sure to perform these steps before continuing in this guide. The remainder of the guide will assume you have created an ExpoKit project. + +## Setting up your project + +By this point you should have a JS app which additionally contains `ios` and `android` directories. + +### 1. Check JS dependencies + +- Your project's `package.json` should contain a `react-native` dependency pointing at Expo's fork of React Native. This should already be configured for you. +- Your JS dependencies should already be installed (via `npm install` or `yarn`). + +### 2. Run the project with Expo CLI + +Run `expo start` from the project directory. + +This step ensures that the React Native packager is running and serving your app's JS bundle for development. Leave this running and continue with the following steps. + +### 3. iOS: Configure, build and run + +This step ensures the native iOS project is correctly configured and ready for development. + +- Make sure you have the latest Xcode. +- If you don't have it already, install [CocoaPods](https://cocoapods.org), which is a native dependency manager for iOS. +- Run `pod install` from your project's `ios` directory. +- Open your project's `xcworkspace` file in Xcode. +- Use Xcode to build, install and run the project on your test device or simulator. (this will happen by default if you click the big "Play" button in Xcode.) + +Once it's running, the iOS app should automatically request your JS bundle from the project you're serving from Expo CLI. + +### 4. Android: Build and run + +Open the `android` directory in Android Studio, then build and run the project on an Android device or emulator. + +When opening the project, Android Studio may prompt you to upgrade the version of Gradle or other build tools, but don't do this as you may get unexpected results. ExpoKit always ships with the latest supported versions of all build tools. + +If you prefer to use the command line, you can run `./run.sh` from inside the `android` directory to build the project and install it on the running device/emulator. + +Once the Android project is running, it should automatically request your development url from Expo CLI. You can develop your project normally from here. + +## Continuing with development + +Every time you want to develop, ensure your project's JS is being served by Expo CLI (step 2), then run the native code from Xcode or Android Studio respectively. + +Your ExpoKit project is configured to load your app's published url when you build it for release. So when you want to release it, don't forget to publish, like with any normal (non-ExpoKit) project. + +## Changing Native Dependencies + +### iOS + +Your ExpoKit project manages its dependencies with [CocoaPods](https://cocoapods.org). + +Many libraries in the React Native ecosystem include instructions to run `react-native link`. These are supported with ExpoKit for iOS. + +- If the library supports CocoaPods (has a .podspec file), just follow the normal instructions and run `react-native link`. +- If the library doesn't support CocoaPods, `react-native link` may fail to include the library's header files. If you encounter build issues locating the `` headers, you may need to manually add `Pods/Headers/Public` to the **Header Search Paths** configuration for your native dependency in Xcode. If you're not familiar with Xcode, search Xcode help for "configure build settings" to get an idea of how those work. **Header Search Paths** is one such build setting. The target you care to configure is the one created by `react-native link` inside your Xcode project. You'll want to determine the relative path from your library to `Pods/Headers/Public`. + +### Android + +Many libraries in the React Native ecosystem include instructions to run `react-native link`. These are supported with ExpoKit for Android. + +## Upgrading ExpoKit + +ExpoKit's release cycle follows the Expo SDK release cycle. When a new version of the Expo SDK comes out, the release notes include upgrade instructions for the normal, JS-only part of your project. Additionally, you'll need to update the native ExpoKit code. + +> **Note:** Please make sure you've already updated your JS dependencies before proceeding with the following instructions. Additionally, there may be version-specific breaking changes not covered here. + +### iOS + +- Open up `ios/Podfile` in your project, and update the `ExpoKit` tag to point at the [release](https://github.com/expo/expo/releases) corresponding to your SDK version. Run `pod update` then `pod install`. +- Open `ios/your-project/Supporting/EXSDKVersions.plist` in your project and change all the values to the new SDK version. + +If upgrading from SDK 31 or below, you'll need to refactor your `AppDelegate` class as we moved its Expo-related part to a separate `EXStandaloneAppDelegate ` class owned by `ExpoKit` to simplify future upgrade processes as much as possible. As of SDK 32, your `AppDelegate` class needs to subclass `EXStandaloneAppDelegate`. + +If you have never made any edits to your Expo-generated `AppDelegate` files, then you can just replace them with these new template files: + +- [AppDelegate.h](https://github.com/expo/expo/blob/master/exponent-view-template/ios/exponent-view-template/AppDelegate.h) +- [AppDelegate.m](https://github.com/expo/expo/blob/master/exponent-view-template/ios/exponent-view-template/AppDelegate.m) + +If you override any `AppDelegate` methods to add custom behavior, you'll need to either refactor your `AppDelegate` to subclass `EXStandaloneAppDelegate` and call `super` methods when necessary, or start with the new template files above and add your custom logic again (be sure to keep the calls to `super` methods). + +If upgrading from SDK 30 or below, you'll also need to change `platform :ios, '9.0'` to `platform :ios, '10.0'` in `ios/Podfile`. + +### Android + +- Go to https://expo.io/--/api/v2/versions and find the `expokitNpmPackage` key under `sdkVersions.[NEW SDK VERSION]`. +- Update your version of expokit in `package.json` to the version in `expokitNpmPackage` and yarn/npm install. +- If upgrading to SDK 31 or below, go to `MainActivity.java` and replace `Arrays.asList("[OLD SDK VERSION]")` with `Arrays.asList("[NEW SDK VERSION]")`. If upgrading to SDK 32 or above, simply remove the entire `public List sdkVersions()` method from `MainActivity.java`. +- Go to `android/app/build.gradle` and replace `compile('host.exp.exponent:expoview:[OLD SDK VERSION]@aar') {` with `compile('host.exp.exponent:expoview:[NEW SDK VERSION]@aar') {`. + +If upgrading from SDK31 or below: +1. add the following lines to `android/app/build.gradle`: + ```groovy + api 'host.exp.exponent:expo-app-loader-provider:1.0.0' + api 'host.exp.exponent:expo-core:2.0.0' + api 'host.exp.exponent:expo-constants-interface:2.0.0' + api 'host.exp.exponent:expo-constants:2.0.0' + api 'host.exp.exponent:expo-errors:1.0.0' + api 'host.exp.exponent:expo-file-system-interface:2.0.0' + api 'host.exp.exponent:expo-file-system:2.0.0' + api 'host.exp.exponent:expo-image-loader-interface:2.0.0' + api 'host.exp.exponent:expo-permissions:2.0.0' + api 'host.exp.exponent:expo-permissions-interface:2.0.0' + api 'host.exp.exponent:expo-sensors-interface:2.0.0' + api 'host.exp.exponent:expo-react-native-adapter:2.0.0' + api 'host.exp.exponent:expo-task-manager:1.0.0' + api 'host.exp.exponent:expo-task-manager-interface:1.0.0' + + // Optional universal modules, could be removed + // along with references in MainActivity + api 'host.exp.exponent:expo-ads-admob:2.0.0' + api 'host.exp.exponent:expo-app-auth:2.0.0' + api 'host.exp.exponent:expo-analytics-segment:2.0.0' + api 'host.exp.exponent:expo-barcode-scanner-interface:2.0.0' + api 'host.exp.exponent:expo-barcode-scanner:2.0.0' + api 'host.exp.exponent:expo-camera-interface:2.0.0' + api 'host.exp.exponent:expo-camera:2.0.0' + api 'host.exp.exponent:expo-contacts:2.0.0' + api 'host.exp.exponent:expo-face-detector:2.0.0' + api 'host.exp.exponent:expo-face-detector-interface:2.0.0' + api 'host.exp.exponent:expo-font:2.0.0' + api 'host.exp.exponent:expo-gl-cpp:2.0.0' + api 'host.exp.exponent:expo-gl:2.0.0' + api 'host.exp.exponent:expo-google-sign-in:2.0.0' + api 'host.exp.exponent:expo-local-authentication:2.0.0' + api 'host.exp.exponent:expo-localization:2.0.0' + api 'host.exp.exponent:expo-location:2.0.0' + api 'host.exp.exponent:expo-media-library:2.0.0' + api 'host.exp.exponent:expo-print:2.0.0' + api 'host.exp.exponent:expo-sensors:2.0.0' + api 'host.exp.exponent:expo-sms:2.0.0' + api 'host.exp.exponent:expo-background-fetch:1.0.0' + ``` +2. Ensure that in `MainActivity.java`, `expoPackages` method looks like this: + ```java + @Override + public List expoPackages() { + return ((MainApplication) getApplication()).getExpoPackages(); + } + ``` +3. In `MainApplication.java`, replace + ```java + public class MainApplication extends ExpoApplication { + ``` + with + ```java + public class MainApplication extends ExpoApplication implements AppLoaderPackagesProviderInterface { + ``` +4. Add the following lines in `MainApplication.java`: + ```java + import expo.core.interfaces.Package; + import expo.loaders.provider.interfaces.AppLoaderPackagesProviderInterface; + import expo.modules.ads.admob.AdMobPackage; + import expo.modules.analytics.segment.SegmentPackage; + import expo.modules.appauth.AppAuthPackage; + import expo.modules.backgroundfetch.BackgroundFetchPackage; + import expo.modules.barcodescanner.BarCodeScannerPackage; + import expo.modules.camera.CameraPackage; + import expo.modules.constants.ConstantsPackage; + import expo.modules.contacts.ContactsPackage; + import expo.modules.facedetector.FaceDetectorPackage; + import expo.modules.filesystem.FileSystemPackage; + import expo.modules.font.FontLoaderPackage; + import expo.modules.gl.GLPackage; + import expo.modules.google.signin.GoogleSignInPackage; + import expo.modules.localauthentication.LocalAuthenticationPackage; + import expo.modules.localization.LocalizationPackage; + import expo.modules.location.LocationPackage; + import expo.modules.medialibrary.MediaLibraryPackage; + import expo.modules.permissions.PermissionsPackage; + import expo.modules.print.PrintPackage; + import expo.modules.sensors.SensorsPackage; + import expo.modules.sms.SMSPackage; + import expo.modules.taskManager.TaskManagerPackage; + + ... + + public List getExpoPackages() { + return Arrays.asList( + new CameraPackage(), + new ConstantsPackage(), + new SensorsPackage(), + new FileSystemPackage(), + new FaceDetectorPackage(), + new GLPackage(), + new GoogleSignInPackage(), + new PermissionsPackage(), + new SMSPackage(), + new PrintPackage(), + new ConstantsPackage(), + new MediaLibraryPackage(), + new SegmentPackage(), + new FontLoaderPackage(), + new LocationPackage(), + new ContactsPackage(), + new BarCodeScannerPackage(), + new AdMobPackage(), + new LocalAuthenticationPackage(), + new LocalizationPackage(), + new AppAuthPackage(), + new TaskManagerPackage(), + new BackgroundFetchPackage() + ); + } + ``` + +If upgrading from SDK 30 or below, remove the following lines from `android/app/build.gradle`: +```groovy +implementation 'com.squareup.okhttp3:okhttp:3.4.1' +implementation 'com.squareup.okhttp3:okhttp-urlconnection:3.4.1' +implementation 'com.squareup.okhttp3:okhttp-ws:3.4.1' +``` + +If upgrading from SDK 28 or below, you'll also need to follow these instructions: + +- Change all instances of `android\\detach-scripts` and `android/detach-scripts` to `node_modules\\expokit\\detach-scripts` and `node_modules/expokit/detach-scripts` respectively in `android/app/expo.gradle`. +- Add `maven { url "$rootDir/../node_modules/expokit/maven" }` under `allprojects.repositories` in `android/build.gradle`. +- In `android/app/build.gradle`, replace +```groovy +compile('host.exp.exponent:expoview:[SDK VERSION]@aar') { + transitive = true +} +``` +with +```groovy +compile('host.exp.exponent:expoview:[SDK VERSION]@aar') { + transitive = true + exclude group: 'com.squareup.okhttp3', module: 'okhttp' + exclude group: 'com.squareup.okhttp3', module: 'okhttp-urlconnection' +} +``` diff --git a/docs/pages/versions/unversioned/expokit/index.md b/docs/pages/versions/unversioned/expokit/index.md new file mode 100644 index 00000000000000..df69849d05ffd4 --- /dev/null +++ b/docs/pages/versions/unversioned/expokit/index.md @@ -0,0 +1,17 @@ +--- +title: ExpoKit +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +ExpoKit is an Objective-C and Java library that allows you to use the Expo platform and your existing Expo project as part of a larger standard native project -- one that you would normally create using Xcode, Android Studio, or `react-native init`. + +Because Expo already provides the ability to [render native binaries for the App Store](../distribution/building-standalone-apps/), most Expo developers do not need to use ExpoKit. In some cases, projects need to make use of third-party Objective-C or Java native code that is not included in the core Expo SDK. ExpoKit provides this ability. + +This documentation will discuss: + +- [Ejecting](eject/) your normal (JS) Expo project into a JS-and-native ExpoKit project +- [Changing your workflow](expokit/) to use custom native code with ExpoKit +- Other [advanced ExpoKit topics](advanced-expokit-topics/) diff --git a/docs/pages/versions/unversioned/expokit/universal-modules-and-expokit.md b/docs/pages/versions/unversioned/expokit/universal-modules-and-expokit.md new file mode 100644 index 00000000000000..6b6aa908383511 --- /dev/null +++ b/docs/pages/versions/unversioned/expokit/universal-modules-and-expokit.md @@ -0,0 +1,65 @@ +--- +title: Universal Modules and ExpoKit +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Universal Modules are pieces of the Expo SDK with some special properties: + +- They are optional; you can remove them from your ExpoKit build if you don't need their native code. +- They can run as standalone libraries without Expo. + +Not all Expo SDK modules are Universal Modules. Right now, only a small part of our SDK has this property. We're continually expanding the number of our APIs that are available as universal modules. + +# Omitting Unneeded Modules + +When you [create an ExpoKit project](../eject/), we automatically add most of the same native APIs that are available in the Expo Client app. Each of these APIs is supported by some native code which increases the size of your native binary. + +You can remove any Expo Universal Module from your ExpoKit project if you don't think you need it. This means it will no longer be available in your native binary; if you write some JS which tries to import this API, you might cause a fatal error in your app. If you send an [OTA update](../../guides/configuring-ota-updates/) to your app which contains API calls that aren't present in your native binary, you might cause a fatal error. + +Omitting Universal Modules is currently supported on iOS but not Android. + +> **If you aren't sure what this guide is for or whether you need this,** you are probably better off just leaving it alone. Otherwise you risk causing crashes in your app by ripping out needed APIs. + +## iOS + +To omit a Universal Module from your iOS ExpoKit project, remove the respective dependency from `ios/Podfile`. Then re-run `pod install` and rebuild your native code. + +### These modules are included by default, but can be omitted + +- GL (`EXGL` and `EXGL-CPP`) +- SMS composer (`EXSMS`) +- Accelerometer, DeviceMotion, Gyroscope, Magnetometer, Pedometer (`EXSensors`) + +### These modules are included by default, but can be dangerously omitted + +Some modules implement core Expo functionality through a generic interface. For example, our `Permissions` module implements `expo-permissions-interface`. If you remove the Permissions module, the project will build, but it may not run unless you add some other code which provides Expo Permissions functionality. + +- Camera (`EXCamera`) +- Constants (`EXConstants`) +- FileSystem (`EXFileSystem`) +- Permissions (`EXPermissions`) + +## Android + +Omitting Universal Modules is not currently supported on Android. + +# Adding Optional Modules on iOS + +A few Expo modules are not included by default in ExpoKit iOS projects, nor in Standalone iOS Apps produced by `expo build`. Typically this is either because they add a disproportionate amount of bloat to the binary, or because they include APIs that are governed by extra Apple review guidelines. Right now those modules are: + +- FaceDetector (`EXFaceDetector`) +- ARKit +- Payments + +If you want to use any of these modules in your Expo iOS app, you need to eject to ExpoKit rather than using `expo build`. (It's on our roadmap to improve this.) + +To add FaceDetector: + +1. Add `expo-face-detector` to `package.json` and install JS dependencies. +2. Add `pod 'EXFaceDetector', path: '../node_modules/expo-face-detector/ios'` to your `Podfile`. +3. Re-run `pod install`. + +To add `Payments` or `AR`, add the [respective subspec](https://github.com/expo/expo/blob/master/ExpoKit.podspec) to your `ExpoKit` dependency in your `Podfile`, and re-run `pod install`. diff --git a/docs/pages/versions/unversioned/guides/app-icons.md b/docs/pages/versions/unversioned/guides/app-icons.md new file mode 100644 index 00000000000000..46653ac23edefa --- /dev/null +++ b/docs/pages/versions/unversioned/guides/app-icons.md @@ -0,0 +1,37 @@ +--- +title: App Icons +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Your app's icon is what users see on the home screen of their devices, as well as in the App Store and Play Store. This is one topic where platform differences matter, and requirements can be strict. This guide offers details on how to make sure your App Icon looks as good as possible on all devices. + +## Configuring your App's Icon + +The most straightforward way to provide an icon for your app is to provide the [icon](../../workflow/configuration/#icon) key in `app.json`. If you want to do the minimum possible, this key alone is sufficient. However, Expo also accepts platform-specific keys under `ios.icon` and `android.icon`. If either of these exist, they will take priority over the base `icon` key on their respective platform. Further customization of the Android icon is possible using the `android.adaptiveIcon` key, which will override both of the previously mentioned settings. Most production-quality apps will probably want to provide something slightly different between iOS and Android. + +## Icon Best Practices + +### iOS + +- The icon you use for iOS should follow the [Apple Human Interface Guidelines](https://developer.apple.com/ios/human-interface-guidelines/icons-and-images/app-icon/) for iOS Icons. +- Use a png file. +- 1024x1024 is a good size. The Expo [build service](../../distribution/building-standalone-apps/) will generate the other sizes for you. The largest size it generates is 1024x1024. +- The icon must be exactly square, i.e. a 1023x1024 icon is not valid. +- Make sure the icon fills the whole square, with no rounded corners or other transparent pixels. The operating system will mask your icon when appropriate. + +### Android + +- The Android Adaptive Icon is formed from two separate layers -- a foreground image and a background color or image. This allows the OS to mask the icon into different shapes and also support visual effects. +- The design you provide should follow the [Android Adaptive Icon Guidelines](https://developer.android.com/guide/practices/ui_guidelines/icon_design_adaptive) for launcher icons. +- Use png files. +- The default background color is white; to specify a different background color, use the `android.adaptiveIcon.backgroundColor` field. You can instead specify a background image using the `android.adaptiveIcon.backgroundImage` field; ensure that it has the same dimensions as your foreground image. +- You may also want to provide a separate icon for older Android devices that do not support Adaptive Icons; you can do so with the `android.icon` field. This single icon would probably be a combination of your foreground and background layers. +- You may still want to follow some of the [Apple best practices](https://developer.apple.com/ios/human-interface-guidelines/icons-and-images/app-icon/) to ensure your icon looks professional, such as testing your icon on different wallpapers, and avoiding text besides your product's wordmark. +- Provide something that's at least 512x512 pixels. Since you already need 1024x1024 for iOS, it won't hurt to just provide that here as well. + +### Expo Client and Web + +- If your app contains `privacy: public` in [app.json](../../workflow/configuration/), it will show up on your expo.io profile. We will mask your icon to have rounded corners in that circumstance, so if it already looks reasonable on iOS, it will probably look good here as well. \ No newline at end of file diff --git a/docs/pages/versions/unversioned/guides/assets.md b/docs/pages/versions/unversioned/guides/assets.md new file mode 100644 index 00000000000000..edabde09dd2157 --- /dev/null +++ b/docs/pages/versions/unversioned/guides/assets.md @@ -0,0 +1,27 @@ +--- +title: Assets +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Images, fonts, videos, sounds, any other file that your app depends on that is not JavaScript is considered to be an _asset_. Just as on the web, assets are fetched or streamed over HTTP on demand. This is different from your typical mobile app, where assets are bundled with your application binary. + +However, there is a distinction in Expo between an asset that you use with the `require` syntax because they are available at build time on your local filesystem, eg: ``, and web images that you refer to by a web URL, eg: ``. We can make no guarantees about the availability of the images that you refer to with a web URI because we don't manage those assets. Additionally, we don't have the same amount of information about arbitrary web URIs: when your assets are available on the local filesystem, the packager is able to read some metadata (width, height, for example) and pass that through to your app, so you actually don't need to specify a width and height, for example. When specifying a remote web URL, you will need to explicitly specify a width and height, or it will default to 0x0. Lastly, as you will see later, caching behaviour is different in both cases. + +The following is an explanation of the former type of assets: those that you have on your filesystem at build time. In the latter case, it is assumed that you are familiar with how to upload an image to somewhere on the web where it can be accessed by any web or mobile app. + +## Where assets live + +### In development + +While you're working on a local copy of your project, assets are served from your local filesystem and are integrated with the JavaScript module system. So if I want to include an image I can `require` it, like I would if it were JavaScript code: `require('./assets/images/example.png')`. The only difference here is that we need to specify an extension -- without an extension, the module system will assume it is a JavaScript file. This statement evaluates at compile time to an object that includes metadata about the asset that can be consumed by the `Image` component to fetch it and render it: `` + +### In production + +Each time you publish your app, Expo will upload your assets to Amazon CloudFront, a blazing fast CDN. It does this in an intelligent way to ensure your deploys remain fast: if an asset has not changed since your previous deploy, it is skipped. You don't have to do anything for this to work, it is all automatically handled by Expo. + +## Performance + +Some assets are too important to start your app without. Fonts often fall into this category. On the web the font loading problem is known by several acronyms: FOUT, FOIT, and FOFT, which stand for Flash of Unstyled Text, Flash of Invisible Text, and Flash of Faux Text ([read more here](https://css-tricks.com/fout-foit-foft/)). The default behaviour with the icon-font-powered [@expo/vector-icons](../icons/#icons) icons is a FOIT on first load, and on subsequent loads the font will be automatically cached. Users have higher standards for mobile than web, so you might want to take it a step further by preloading and caching the font and important images during the initial loading screen. diff --git a/docs/pages/versions/unversioned/guides/configuring-ota-updates.md b/docs/pages/versions/unversioned/guides/configuring-ota-updates.md new file mode 100644 index 00000000000000..135e9a7eeffcdd --- /dev/null +++ b/docs/pages/versions/unversioned/guides/configuring-ota-updates.md @@ -0,0 +1,50 @@ +--- +title: Configuring OTA Updates +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Expo provides various settings to configure how your app receives over-the-air (OTA) JavaScript updates. OTA updates allow you to publish a new version of your app JavaScript and assets without building a new version of your standalone app and re-submitting to app stores ([read more about the limitations](../../workflow/publishing/)). + +To perform an over-the-air update of your app, you simply run `expo publish`. If you're using release channels, specify one with `--release-channel ` option. Please note that if you wish to update the SDK version which your app is using, you need to rebuild your app with `expo build:*` command and upload the binary file to the appropriate app store ([see the docs here](../../distribution/building-standalone-apps)). + +OTA updates are controlled by the [`updates` settings in app.json](../../workflow/configuration/#updates), which handle the initial app load, and the [Updates SDK module](../../sdk/updates/), which allows you to fetch updates asynchronously from your JS. + +## Automatic Updates + +By default, Expo will check for updates automatically when your app is launched and will try to fetch the latest published version. If a new bundle is available, Expo will attempt to download it before launching the experience. If there is no network connection available, or it has not finished downloading in 30 seconds, Expo will fall back to loading a cached version of your app, and continue trying to fetch the update in the background (at which point it will be saved into the cache for the next app load). + +With this automatic configuration, calling [`Expo.Updates.reload()`](../../sdk/updates/#expoupdatesreload) will also result in Expo attempting to fetch the most up-to-date version of your app, so there is no need to use any of the other methods in the Updates module. + +The timeout length is configurable by setting `updates.fallbackToCacheTimeout` (ms) in app.json. For example, a common pattern is to set `updates.fallbackToCacheTimeout` to `0`. This will allow your app to start immediately with a cached bundle while downloading a newer one in the background for future use. [`Expo.Updates.addListener`](../../sdk/updates/#expoupdatesaddlistenereventlistener) provides a hook to let you respond when the new bundle is finished downloading. + +## Manual Updates + +In standalone apps, it is also possible to turn off automatic updates, and to instead control updates entirely within your JS code. This is desirable if you want some custom logic around fetching updates (e.g. only over Wi-Fi). + +Setting `updates.checkAutomatically` to `"ON_ERROR_RECOVERY"` in app.json will prevent Expo from automatically fetching the latest update every time your app is launched. Only the most recent cached version of your bundle will be loaded. It will only automatically fetch an update if the last run of the cached bundle produced a fatal JS error. + +You can then use the [`Expo.Updates`](../../sdk/updates/) module to download new updates and, if appropriate, notify the user and reload the experience. + +```javascript +try { + const update = await Expo.Updates.checkForUpdateAsync(); + if (update.isAvailable) { + await Expo.Updates.fetchUpdateAsync(); + // ... notify user of update ... + Expo.Updates.reloadFromCache(); + } +} catch (e) { + // handle or log error +} +``` + +Note that `checkAutomatically: "ON_ERROR_RECOVERY"` will be ignored in the Expo client, although the imperative Updates methods will still function normally. + +## Disabling Updates + +It is possible to entirely disable OTA JavaScript updates in a standalone app, by setting `updates.enabled` to `false` in app.json. This will ignore all code paths that fetch app bundles from Expo's servers. In this case, all updates to your app will need to be routed through the iOS App Store and/or Google Play Store. + +This setting is ignored in the Expo client. diff --git a/docs/pages/versions/unversioned/guides/configuring-statusbar.md b/docs/pages/versions/unversioned/guides/configuring-statusbar.md new file mode 100644 index 00000000000000..ad5eda9bcd88f3 --- /dev/null +++ b/docs/pages/versions/unversioned/guides/configuring-statusbar.md @@ -0,0 +1,86 @@ +--- +title: Configuring StatusBar +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Expo and React Native provide APIs and configuration options for Android to configure the status bar for your app. These can be used to control the appearance of the status bar in your app. + +## Configuration (Android) + +The configuration for Android status bar lives under the `androidStatusBar` key in `app.json`. It exposes the following options: + +### `barStyle` + +This option can be used to specify whether the status bar content (icons and text in the status bar) is light, or dark. Usually a status bar with a light background has dark content, and a status bar with a dark background has light content. + +The valid values are: + +- `light-content` - The status bar content is light colored (usually white). This is the default value. +- `dark-content` - The status bar content is dark colored (usually dark grey). This is only available on Android 6.0 onwards. It will fallback to `light-content` in older versions. + +### `backgroundColor` + +This option can be used to set a background color for the status bar. + +Keep in mind that the Android status bar is translucent by default in Expo apps. But, when you specify an opaque background color for the status bar, it'll lose it's translucency. + +The valid value is a hexadecimal color string. e.g. - #C2185B + +## Working with 3rd-party Libraries + +Expo makes the status bar translucent by default on Android which is consistent with iOS, and more in line with material design. Unfortunately some libraries don't support translucent status bar, e.g. - navigation libraries, libraries which provide a header bar etc. + +If you need to use such a library, there are a few options: + +### Set the `backgroundColor` of the status bar to an opaque color + +This will disable the translucency of the status bar. This is a good option if your status bar color never needs to change. + +Example: + +```json +{ + "expo": { + "androidStatusBar": { + "backgroundColor": "#C2185B" + } + } +} +``` + +### Use the [`StatusBar` API from React Native](https://facebook.github.io/react-native/docs/statusbar.html) + +The `StatusBar` API allows you to dynamically control the appearance of the status bar. You can use it as component, or as an API. Check the documentation on the React Native website for examples. + +## Place an empty `View` on top of your screen + +You can place an empty `View` on top of your screen with a background color to act as a status bar, or set a top padding. You can get the height of the status bar with `Expo.Constants.statusBarHeight`. Though this should be your last resort since this doesn't work very well when status bar's height changes. + +Example: + +```js +import React from 'react'; +import { StyleSheet, View } from 'react-native'; +import { Constants } from 'expo'; + +const styles = StyleSheet.create({ + statusBar: { + backgroundColor: "#C2185B", + height: Constants.statusBarHeight, + }, + + // rest of the styles +}); + +const MyComponent = () => { + + + {/* rest of the content */} + +} +``` + +If you don't need to set the background color, you can just set a top padding on the wrapping `View` instead. diff --git a/docs/pages/versions/unversioned/guides/errors.md b/docs/pages/versions/unversioned/guides/errors.md new file mode 100644 index 00000000000000..dd429728102620 --- /dev/null +++ b/docs/pages/versions/unversioned/guides/errors.md @@ -0,0 +1,33 @@ +--- +title: Error Handling +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +This guide details a few strategies available for reporting and recovering from errors in your project. + +## Handling Fatal JS Errors + +If your app encounters a fatal JS error, Expo will report the error differently depending on whether your app is in development or production. + +**In Development:** If you're serving your app from Expo CLI, the fatal JS error will be reported to the [React Native RedBox](https://facebook.github.io/react-native/docs/debugging.html#in-app-errors-and-warnings) and no other action will be taken. + +**In Production:** If your published app encounters a fatal JS error, Expo will immediately reload your app. If the error happens very quickly after reloading, Expo will show a generic error screen with a button to try manually reloading. + +Expo can also report custom information back to you after your app reloads. If you use `ErrorRecovery.setRecoveryProps`, and the app later encounters a fatal JS error, the contents of that method call will be passed back into your app's initial props upon reloading. See [Expo.ErrorRecovery](../../sdk/error-recovery/). + +## Tracking JS Errors + +We recommend using [Sentry](../../guides/using-sentry) to track JS errors in production and configuring our post-publish hook to keep your source maps up to date. + +## What about Native Errors? + +Since Expo's native code never changes with regard to your project, the native symbols aren't especially meaningful (they would show you a trace into the React Native core or into Expo's native SDK). In the vast majority of circumstances *, the JS error is what you care about. + +Nonetheless, if you really want native crash logs and are deploying your app as a [standalone app](../../distribution/building-standalone-apps/), you can configure custom Fabric keys for Android. See [Configuration with app.json](../../workflow/configuration/). + +For iOS, right now we don't expose a way for you to see native crash logs from your Expo app. This is because we don't build iOS native code on demand, which would be a requirement for uploading your debug symbols to Fabric (or a similar service). + +`*` There are a few circumstances where it's possible to crash native code by writing bad JS. Usually these are in areas where it would be performance-prohibitive to add native validation to your code, e.g. the part of the React Native bridge that converts JS objects into typed native values. If you encounter an inexplicable native crash, double check that your parameters are of the right type. \ No newline at end of file diff --git a/docs/pages/versions/unversioned/guides/icons.md b/docs/pages/versions/unversioned/guides/icons.md new file mode 100644 index 00000000000000..785f2d3ba3f244 --- /dev/null +++ b/docs/pages/versions/unversioned/guides/icons.md @@ -0,0 +1,139 @@ +--- +title: Icons +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +As trendy as it is these days, not every app has to use emoji for all icons 😳 -- maybe you want to pull in a popular set through an icon font like FontAwesome, Glyphicons or Ionicons, or you just use some PNGs that you carefully picked out on [The Noun Project](https://thenounproject.com/) (Expo does not currently support SVGs). Let's look at how to do both of these approaches. + +## @expo/vector-icons + +This library is installed by default on the template project that get through `expo init` -- it is part of the `expo` package. It includes popular icon sets and you can browse all of the icons using the [@expo/vector-icons directory](https://expo.github.io/vector-icons/). + +```javascript +import React from 'react'; +import { Ionicons } from '@expo/vector-icons'; + +export default class IconExample extends React.Component { + render() { + return ( + + ); + } +} +``` + +This component loads the Ionicons font if it hasn't been loaded already, and renders a checkmark icon that I found through the vector-icons directory mentioned above. `@expo/vector-icons` is built on top of [react-native-vector-icons](https://github.com/oblador/react-native-vector-icons) and uses a similar API. The only difference is `@expo/vector-icons` uses a more idiomatic `import` style: + +`import { Ionicons } from '@expo/vector-icons';` instead of.. `import Ionicons from 'react-native-vector-icons/Ionicons';`. + +> **Note:** As with [any custom font](../using-custom-fonts/#using-custom-fonts) in Expo, you may want to preload icon fonts before rendering your app. The font object is available as a static property on the font component, so in the case above it is `Ionicons.font`, which evaluates to `{ionicons: require('path/to/ionicons.ttf')}`. [Read more about preloading assets](../preloading-and-caching-assets/). + +## Custom Icon Fonts + +First, make sure you import your custom icon font. [Read more about loading custom fonts](../using-custom-fonts/#using-custom-fonts). Once your font has loaded, you'll need to create an Icon Set. `@expo/vector-icons` exposes three methods to help you create an icon set. + +### createIconSet + +Returns your own custom font based on the `glyphMap` where the key is the icon name and the value is either a UTF-8 character or it's character code. `fontFamily` is the name of the font **NOT** the filename. See [react-native-vector-icons](https://github.com/oblador/react-native-vector-icons/blob/master/README.md#custom-fonts) for more details. + +```javascript +import { Font } from 'expo'; +import { createIconSet } from '@expo/vector-icons'; +const glyphMap = { 'icon-name': 1234, test: '∆' }; +const CustomIcon = createIconSet(glyphMap, 'FontName'); + +export default class CustomIconExample extends React.Component { + state = { + fontLoaded: false + } + async componentDidMount() { + await Font.loadAsync({ + 'FontName': require('assets/fonts/custom-icon-font.ttf') + }); + + this.setState({fontLoaded: true}); + } + render() { + if (!this.state.fontLoaded) { return null;} + + return ( + + ); + } +} +``` + +### createIconSetFromFontello + +Convenience method to create a custom font based on a [Fontello](http://fontello.com/) config file. Don't forget to import the font as described above and drop the `config.json` somewhere convenient in your project, using `Font.loadAsync`. + +```javascript +// Once your custom font has been loaded... +import { createIconSetFromFontello } from '@expo/vector-icons'; +import fontelloConfig from './config.json'; +const Icon = createIconSetFromFontello(fontelloConfig, 'FontName'); +``` + +### createIconSetFromIcoMoon + +Convenience method to create a custom font based on an [IcoMoon](https://icomoon.io/) config file. Don't forget to import the font as described above and drop the `config.json` somewhere convenient in your project, using `Font.loadAsync`. + +```javascript +// Once your custom font has been loaded... +import { createIconSetFromIcoMoon } from '@expo/vector-icons'; +import icoMoonConfig from './config.json'; +const Icon = createIconSetFromIcoMoon(icoMoonConfig, 'FontName'); +``` + +## Icon images + +If you know how to use the react-native `` component this will be a breeze. + +```javascript +import React from 'react'; +import { Image } from 'react-native'; + +export default class SlackIcon extends React.Component { + render() { + return ( + + ); + } +} +``` + +Let's assume that our `SlackIcon` class is located in `my-project/components/SlackIcon.js`, and our icon images are in `my-project/assets/images`, in order to refer to the image we use require and include the relative path. You can provide versions of your icon at various pixel densities and the appropriate image will be automatically used for you. In this example, we actually have `slack-icon@2x.png` and `slack-icon@3x.png`, so if I view this on an iPhone 6s the image I will see is `slack-icon@3x.png`. More on this in the [Images guide in the react-native documentation](https://facebook.github.io/react-native/docs/images.html#static-image-resources). + +We also set the `fadeDuration` (an Android specific property) to `0` because we usually want the icon to appear immediately rather than fade in over several hundred milliseconds. + +## Button Component +A convenience component for creating buttons with an icon on the left side. + +```js +import { FontAwesome } from '@expo/vector-icons'; + +const myButton = ( + + Login with Facebook + +); +``` + +### Properties +Any [`Text`](http://facebook.github.io/react-native/docs/text.html), [`TouchableHighlight`](http://facebook.github.io/react-native/docs/touchablehighlight.html) or [`TouchableWithoutFeedback`](http://facebook.github.io/react-native/docs/touchablewithoutfeedback.html) property in addition to these: + +| Prop | Description | Default | +|---|---|---| +|**`color`**|Text and icon color, use `iconStyle` or nest a `Text` component if you need different colors.|`white`| +|**`size`**|Icon size.|`20`| +|**`iconStyle`**|Styles applied to the icon only, good for setting margins or a different color. *Note: use `iconStyle` for margins or expect unstable behaviour.*|\`{marginRight: 10}\`| +|**`backgroundColor`**|Background color of the button.|`#007AFF`| +|**`borderRadius`**|Border radius of the button, set to `0` to disable. |`5`| +|**`onPress`**|A function called when the button is pressed. |*None*| diff --git a/docs/pages/versions/unversioned/guides/index.md b/docs/pages/versions/unversioned/guides/index.md new file mode 100644 index 00000000000000..5d386f4f294df9 --- /dev/null +++ b/docs/pages/versions/unversioned/guides/index.md @@ -0,0 +1,9 @@ +--- +title: Guides +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +These guides cover specific goals or features you might want to implement in your Expo project. For example, many people want to [load custom fonts](using-custom-fonts/) besides those which come with the device, or [send push notifications](push-notifications/) to their users. Read whichever guide suits your needs. diff --git a/docs/pages/versions/unversioned/guides/notification-channels.md b/docs/pages/versions/unversioned/guides/notification-channels.md new file mode 100644 index 00000000000000..4ead67d48e6790 --- /dev/null +++ b/docs/pages/versions/unversioned/guides/notification-channels.md @@ -0,0 +1,124 @@ +--- +title: Notification Channels +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Notification channels are a new feature in Android Oreo that give users more control over the notifications they receive. Starting in Android Oreo, every local and push notification must be assigned to a single channel. Users can see all notification channels in their OS Settings, and they can customize the behavior of alerts on a per-channel basis. + +Notification channels have no effect and are ignored on all iOS devices. + +## Designing channels + +Channels give users more control over the various kinds of alerts they want to receive from your app. You should create a channel for each type of notification you might send, such as Alarms, Chat messages, Update notifications, or the like. + +According to the Android developer documentation: + +>You should create a channel for each distinct type of notification you need to send. You can also create notification channels to reflect choices made by users of your app. For example, you can set up separate notification channels for each conversation group created by a user in a messaging app. + +When you create a channel, you can specify various settings for its notifications, such as priority, sound, and vibration. After you create the channel, control switches entirely to the user, who can then customize these settings to their own liking for each channel. Your app can no longer change any of the settings. Although it is possible for your app to programmatically delete channels, Android does not recommend this and keeps a relic on the user's device. + +You can read more about notification channels on the [Android developer website](https://developer.android.com/training/notify-user/channels). It's a good idea to put some thought into designing channels that make sense and are useful customization tools for your users. + +## Creating and using channels + +Creating a channel is easy -- before you create a local notification (or receive a push notification), simply call the following method: + +```javascript +if (Platform.OS === 'android') { + Expo.Notifications.createChannelAndroidAsync('chat-messages', { + name: 'Chat messages', + sound: true, + }); +} +``` + +Creating a channel that already exists is essentially a no-op, so it's safe to call this each time your app starts up. For example, the `componentDidMount` of your app's root component might be a good place for this. However, note that you cannot change any settings of a notification channel after it's been created -- only the user can do this. So be sure to plan your channels carefully. + +Then, when you want to send a notification for a chat message, either add the `channelId: 'chat-messages'` field to your [push notification message](../push-notifications/#message-format), or create a local notification like this: + +```javascript +Expo.Notifications.presentLocalNotificationAsync({ + title: 'New Message', + body: 'Message!!!!', + android: { + channelId: 'chat-messages', + }, +}); +``` + +Expo will then present your notification to the user through the `chat-messages` channel, respecting all of the user's settings for that channel. + +If you create a notification and do not specify a `channelId`, Expo will automatically create a 'Default' channel for you and present the notification through that channel. If, however, you specify a `channelId` that has not yet been created on the device, __the notification will not be shown on Android 8+ devices.__ Therefore, it's important to plan ahead and make sure that you create all of the channels you may need before sending out notifications. + +On devices with Android 7 and below, which don't support notification channels, Expo will remember the relevant settings you created the channel with (in this case, `sound: true`) and apply them directly to the individual notification before presenting it to the user. + +## Updating an existing app to use channels + +If you have an existing Android app that relies on `sound`, `vibrate`, or `priority` settings for notifications, you'll need to update it to take advantage of channels, as those settings no longer have any effect on individual notifications. If you do not rely on those settings, you may want to update it anyway in order to give users more control over the different types of notifications your app presents. (Note that the client-side `priority` setting involved here only affects the notification's UI behavior and is distinct from [the `priority` of a push notification](../push-notifications/#message-format), which is not affected by notification channels.) + +To do this, first make sure you are using the latest minor update of `expo` for your SDK version. Notification channels are supported in SDKs 22 and above, so for example, if you're on SDK 27 you should `npm install`/`yarn add` `expo@^27.1.0`. + +Next, plan out the notification channels your app will need. These may correspond to the different permutations of the `sound`, `vibrate` and `priority` settings you used on individual notifications. + +Once you've decided on a set of channels, you need to add logic to your app to create them. We recommend simply creating all channels in `componentDidMount` of your app's root component; this way all users will be sure to get all channels and not miss any notifications. + +For example, if this is your code before: + +```javascript +_createNotificationAsync = () => { + Expo.Notifications.presentLocalNotificationAsync({ + title: 'Reminder', + body: 'This is an important reminder!!!!', + android: { + priority: 'max', + vibrate: [0, 250, 250, 250], + color: '#FF0000', + }, + }); +} +``` + +You might change it to something like this: + +```javascript +componentDidMount() { + // ... + if (Platform.OS === 'android') { + Expo.Notifications.createChannelAndroidAsync('reminders', { + name: 'Reminders', + priority: 'max', + vibrate: [0, 250, 250, 250], + }); + } +} + +// ... + +_createNotificationAsync = () => { + Expo.Notifications.presentLocalNotificationAsync({ + title: 'Reminder', + body: 'This is an important reminder!!!!', + android: { + channelId: 'reminders', + color: '#FF0000', + }, + }); +} +``` + +This will create a channel called "Reminders" with default settings of `max` priority and the vibrate pattern `[0, 250, 250, 250]`. Android 8 users can change these settings whenever they want, or even turn off notifications completely for the "Reminders" channel. When `presentLocalNotificationAsync` is called, the OS will read the channel's settings and present the notification accordingly. + +## Send channel notification with Expo api service. + ```javascript +[{ + "to": "ExponentPushToken[xxxxxx]", + "title":"test", + "priority":"high", + "body": "test", + "sound":"default", // android 7.0 , 6, 5 , 4 + "channelId": "chat-messages", // android 8.0 later +}] +``` diff --git a/docs/pages/versions/unversioned/guides/offline-support.md b/docs/pages/versions/unversioned/guides/offline-support.md new file mode 100644 index 00000000000000..ec840a13718f11 --- /dev/null +++ b/docs/pages/versions/unversioned/guides/offline-support.md @@ -0,0 +1,42 @@ +--- +title: Offline Support +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Your app will encounter circumstances where the internet connection is sub-par or totally unvailable and it still needs to work reasonably well. This guide offers more information and best practices for providing a great experience while the device is offline. + +## Load JS updates in the background + +When you [publish](../../workflow/publishing/) an update to your app, your users will receieve the new version of your JS over the air. The new version will download either next time the app starts, or next time you call [Updates.reload()](../../sdk/updates/). This behavior also applies the very first time the user opens your app. + +Expo offers multiple behaviors for how it should download your JS. It can either block the UI with a [splash screen](../splash-screens/) or [AppLoading component](../../sdk/app-loading/) until the new JS is downloaded, or it can immediately show an old version of your JS and download the update in the background. The former option is better if your users must have the latest version at all times; the latter option is better if you have a bad internet connection and need to show something right away. + +To force JS updates to run in the background (rather than synchronously checking and downloading on app start), set `updates.fallbackToCacheTimeout` to `0` in `app.json`. You can also listen to see when a new version has finished downloading. For more information, see [Configuring OTA Updates](../configuring-ota-updates/). + +## Cache your assets after downloading + +By default, all of your assets (images, fonts, etc.) are [uploaded to Expo's CDN](../assets/) when you publish updates to your app, which allows you to update them over the air. Once they're downloaded, you can [cache them](../preloading-and-caching-assets/) so you don't need to download them a second time. If you publish changes, the cache will be invalidated and the changed version will be downloaded. + +## Bundle your assets inside your standalone binary + +Expo can bundle assets into your standalone binary during the build process so that they will be available immediately, even if the user has never run your app before. This is important if: + +- Your users may not have internet the first time they open your app, or +- If your app relies on a nontrivial amount of assets for the very first screen to function properly. + +To bundle assets in your binary, use the [assetBundlePatterns](../../workflow/configuration/) key in `app.json` to provide a list of paths in your project directory: + +``` +"assetBundlePatterns": [ + "assets/images/*" +], +``` + +Images with paths matching the given patterns will be bundled into your native binaries next time you run `expo build`. + +## Listen for changes in network availability + +React Native exposes the [NetInfo](https://facebook.github.io/react-native/docs/netinfo.html) API, which informs you if your device's reachability changes. You may want to change your UI (e.g. show a banner, or disable some functions) if you notice that there's no connection available. diff --git a/docs/pages/versions/unversioned/guides/preloading-and-caching-assets.md b/docs/pages/versions/unversioned/guides/preloading-and-caching-assets.md new file mode 100644 index 00000000000000..6a96651e02de9f --- /dev/null +++ b/docs/pages/versions/unversioned/guides/preloading-and-caching-assets.md @@ -0,0 +1,75 @@ +--- +title: Preloading & Caching Assets +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Assets are cached differently depending on where they're stored and how they're used. This guide offers best practices for making sure you only download assets when you need to. In order to keep the loading screen visible while caching assets, it's also a good idea to render [Expo.AppLoading](../../sdk/app-loading/#app-loading) and only that component until everything is ready. See also: [Offline Support](../offline-support/). + +For images that saved to the local filesytem, use `Expo.Asset.fromModule(image).downloadAsync()` to download and cache the image. There is also a [loadAsync()](../../sdk/asset/#expoassetloadasyncmodules) helper method to cache a batch of assets. + +For web images, use `Image.prefetch(image)`. Continue referencing the image normally, e.g. with ``. + +Fonts are preloaded using `Expo.Font.loadAsync(font)`. The `font` +argument in this case is an object such as the following: `{OpenSans: +require('./assets/fonts/OpenSans.ttf')}`. `@expo/vector-icons` provides a helpful shortcut for this object, which you see below as `FontAwesome.font`. + +```javascript +import React from 'react'; +import { AppLoading, Asset, Font } from 'expo'; +import { View, Text, Image } from 'react-native'; +import { FontAwesome } from '@expo/vector-icons'; + +function cacheImages(images) { + return images.map(image => { + if (typeof image === 'string') { + return Image.prefetch(image); + } else { + return Asset.fromModule(image).downloadAsync(); + } + }); +} + +function cacheFonts(fonts) { + return fonts.map(font => Font.loadAsync(font)); +} + +export default class AppContainer extends React.Component { + state = { + isReady: false, + }; + + async _loadAssetsAsync() { + const imageAssets = cacheImages([ + 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png', + require('./assets/images/circle.jpg'), + ]); + + const fontAssets = cacheFonts([FontAwesome.font]); + + await Promise.all([...imageAssets, ...fontAssets]); + } + + render() { + if (!this.state.isReady) { + return ( + this.setState({ isReady: true })} + onError={console.warn} + /> + ); + } + + return ( + + Hello world, this is my app. + + ); + } +} +``` + +See a full working example in [github/expo/new-project-template](https://github.com/expo/new-project-template/blob/master/App.js). diff --git a/docs/pages/versions/unversioned/guides/push-notifications.md b/docs/pages/versions/unversioned/guides/push-notifications.md new file mode 100644 index 00000000000000..e4da492267a6d0 --- /dev/null +++ b/docs/pages/versions/unversioned/guides/push-notifications.md @@ -0,0 +1,431 @@ +--- +title: Push Notifications +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Push Notifications are an important feature to, as _"growth hackers"_ would say, retain and re-engage users and monetize on their attention, or something. From my point of view it's just super handy to know when a relevant event happens in an app so I can jump back into it and read more. Let's look at how to do this with Expo. Spoiler alert: it's almost too easy. + +> **Note:** iOS and Android simulators cannot receive push notifications. To test them out you will need to use a real-life device. Additionally, when calling Permissions.askAsync on the simulator, it will resolve immediately with "undetermined" as the status, regardless of whether you choose to allow or not. + +There are three main steps to wiring up push notifications: sending a user's Expo Push Token to your server, calling Expo's Push API with the token when you want to send a notification, and responding to receiving and/or selecting the notification in your app (for example to jump to a particular screen that the notification refers to). + +## 1. Save the user's Expo Push Token on your server + +In order to send a push notification to somebody, we need to know about their device. Sure, we know our user's account information, but Apple, Google, and Expo do not understand what devices correspond to "Brent" in your proprietary user account system. Expo takes care of identifying your device with Apple and Google through the Expo push token, which is unique each time an app is installed on a device. All we need to do is send this token to your server so you can associate it with the user account and use it in the future for sending push notifications. + +![Diagram explaining saving tokens](/static/images/saving-token.png) + +```javascript +import { Permissions, Notifications } from 'expo'; + +const PUSH_ENDPOINT = 'https://your-server.com/users/push-token'; + +async function registerForPushNotificationsAsync() { + const { status: existingStatus } = await Permissions.getAsync( + Permissions.NOTIFICATIONS + ); + let finalStatus = existingStatus; + + // only ask if permissions have not already been determined, because + // iOS won't necessarily prompt the user a second time. + if (existingStatus !== 'granted') { + // Android remote notification permissions are granted during the app + // install, so this will only ask on iOS + const { status } = await Permissions.askAsync(Permissions.NOTIFICATIONS); + finalStatus = status; + } + + // Stop here if the user did not grant permissions + if (finalStatus !== 'granted') { + return; + } + + // Get the token that uniquely identifies this device + let token = await Notifications.getExpoPushTokenAsync(); + + // POST the token to your backend server from where you can retrieve it to send push notifications. + return fetch(PUSH_ENDPOINT, { + method: 'POST', + headers: { + Accept: 'application/json', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + token: { + value: token, + }, + user: { + username: 'Brent', + }, + }), + }); +} +``` + +## 2. Call Expo's Push API with the user's token + +Push notifications have to come from somewhere, and that somewhere is your server, probably (you could write a command line tool to send them if you wanted, it's all the same). When you're ready to send a push notification, grab the Expo push token off of the user record and send it over to the Expo API using a plain old HTTPS POST request. We've taken care of wrapping that for you in a few languages: + +![Diagram explaining sending a push from your server to device](/static/images/sending-notification.png) + +- [expo-server-sdk-node](https://github.com/expo/expo-server-sdk-node) for Node.js. Maintained by the Expo team. +- [expo-server-sdk-python](https://github.com/expo/expo-server-sdk-python) for Python. Maintained by community developers. +- [expo-server-sdk-ruby](https://github.com/expo/expo-server-sdk-ruby) for Ruby. Maintained by community developers. +- [expo-server-sdk-rust](https://github.com/expo/expo-server-sdk-rust) for Rust. Maintained by community developers. +- [ExpoNotificationsBundle](https://github.com/solvecrew/ExpoNotificationsBundle) for Symfony. Maintained by SolveCrew. +- [exponent-server-sdk-php](https://github.com/Alymosul/exponent-server-sdk-php) for PHP. Maintained by community developers. +- [exponent-server-sdk-golang](https://github.com/oliveroneill/exponent-server-sdk-golang) for Golang. Maintained by community developers. +- [exponent-server-sdk-elixir](https://github.com/rdrop/exponent-server-sdk-elixir) for Elixir. Maintained by community developers. + +Check out the source if you would like to implement it in another language. + +> **Note:** For Android, you'll also need to upload your Firebase Cloud Messaging server key to Expo so that Expo can send notifications to your app. **This step is necessary** unless you are not creating your own APK and using just the Expo Client app from Google Play. Follow the guide on [Using FCM for Push Notifications](../../guides/using-fcm) to learn how to create a Firebase project, get your FCM server key,and upload the key to Expo. + +The [Expo push notification tool](https://expo.io/dashboard/notifications) is also useful for testing push notifications during development. It lets you easily send test notifications to your device. + +## 3. Handle receiving and/or selecting the notification + +For Android, this step is entirely optional -- if your notifications are purely informational and you have no desire to handle them when they are received or selected, you're already done. Notifications will appear in the system notification tray as you've come to expect, and tapping them will open/foreground the app. + +For iOS, you would be wise to handle push notifications that are received while the app is foregrounded, because otherwise the user will never see them. Notifications that arrive while the app are foregrounded on iOS do not show up in the system notification list. A common solution is to just show the notification manually. For example, if you get a message on Messenger for iOS, have the app foregrounded, but do not have that conversation open, you will see the notification slide down from the top of the screen with a custom notification UI. + +Thankfully, handling push notifications is straightforward with Expo, all you need to do is add a listener to the `Notifications` object. + +```javascript +import React from 'react'; +import { + Notifications, +} from 'expo'; +import { + Text, + View, +} from 'react-native'; + +// This refers to the function defined earlier in this guide +import registerForPushNotificationsAsync from './registerForPushNotificationsAsync'; + +export default class AppContainer extends React.Component { + state = { + notification: {}, + }; + + componentDidMount() { + registerForPushNotificationsAsync(); + + // Handle notifications that are received or selected while the app + // is open. If the app was closed and then opened by tapping the + // notification (rather than just tapping the app icon to open it), + // this function will fire on the next tick after the app starts + // with the notification data. + this._notificationSubscription = Notifications.addListener(this._handleNotification); + } + + _handleNotification = (notification) => { + this.setState({notification: notification}); + }; + + render() { + return ( + + Origin: {this.state.notification.origin} + Data: {JSON.stringify(this.state.notification.data)} + + ); + } +} +``` + +### Notification handling timing + +It's not entirely clear from the above when your app will be able to handle the notification depending on it's state at the time the notification is received. For clarification, see the following table: + +| Push was received when... | Android | iOS | +| ------------------------------------------------|:-----------------:| -----------------:| +| App is open and foregrounded | Exponent.notification: origin: "received", data: Object | Same as Android +| App is open and backgrounded | Can only be handled if the notification is selected. If it is dismissed, app cannot know it was received. | Same as Android +| App is open and backgrounded, then foregrounded by selecting the notification | Exponent.notification: origin: "selected" | Exponent.notification: origin: "received" | +| App was not open, and then opened by selecting the push notification | Passed as props.exp.notification on app root component | props.exp.notification: origin: "selected" | props.exp.notification | props.exp.notification: origin: "received" | +| App was not open, and then opened by tapping the home screen icon | Can only be handled if the notification is selected. If it is dismissed, the app cannot know it was received. | Same as Android + +## HTTP/2 API + +Although there are server-side SDKs in several languages to help you send push notifications, you may want to directly send requests to our HTTP/2 API. + +### Sending notifications + +Send a POST request to `https://exp.host/--/api/v2/push/send` with the following HTTP headers: + +``` +host: exp.host +accept: application/json +accept-encoding: gzip, deflate +content-type: application/json +``` + +The Expo server also optionally accepts gzip-compressed request bodies. This can greatly reduce the amount of upload bandwidth needed to send large numbers of notifications. The [Node SDK](https://github.com/expo/expo-server-sdk-node) automatically gzips requests for you. + +This API currently does not require any authentication. + +This is a "hello world" request using cURL (replace the placeholder push token with your own): + +```bash +curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/send" -d '{ + "to": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]", + "title":"hello", + "body": "world" +}' +``` + +The HTTP request body must be JSON. It may either be a single message object or an array of up to 100 messages. **We recommend using an array when you want to send multiple messages to efficiently minimize the number of requests you need to make to Expo servers.** This is an example request body that sends two messages: + +```json +[{ + "to": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]", + "sound": "default", + "body": "Hello world!" +}, { + "to": "ExponentPushToken[yyyyyyyyyyyyyyyyyyyyyy]", + "badge": 1, + "body": "You've got mail" +}] +``` + +Upon success, the HTTP response will be a JSON object whose `data` field is an array of **push tickets**, each of which corresponds to the message at its respective index in the request. Continuing the above example, this is what a successful response body looks like: + +```json +{ + "data": [ + {"status": "ok", "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"}, + {"status": "ok", "id": "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY} + ] +} +``` + +If you send a single message that isn't wrapped in an array, the `data` field will be the push ticket also not wrapped in an array. + +#### Push tickets + +Each push ticket indicates whether Expo successfully received the notification and, when successful, a receipt ID to later retrieve a push receipt. When there is an error receiving a message, the ticket's status will be "error" and the ticket will contain information about the error and might not contain a receipt ID. More information about the response format is documented below. + +> **Note:** Even if a ticket says "ok", it doesn't guarantee that the notification will be delivered nor that the device has received the message; "ok" in a push ticket means that Expo successfully received the message and enqueued it to be delivered to the Android or iOS push notification service. + +#### Push receipts + +After receiving a batch of notifications, Expo enqueues each notification to be delivered to the iOS and Android push notification services (APNs and FCM, respectively). Most notifications are typically delivered within a few seconds. Sometimes it may take longer to deliver notifications, particularly if the iOS or Android push notification services are taking longer than usual to receive and deliver notifications, or if Expo's cloud infrastructure is under high load. Once Expo delivers a notification to the iOS or Android push notification service, Expo creates a **push receipt** that indicates whether the iOS or Android push notification service successfully received the notification. If there was an error delivering the notification, perhaps due to faulty credentials or service downtime, the push receipt will contain information about the error. + +To fetch the push receipts, send a POST request to `https://exp.host/--/api/v2/push/getReceipts`. The request body must be a JSON object with a field name "ids" that is an array of receipt ID strings: + +```bash +curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/getReceipts" -d '{ + "ids": ["XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY"] +}' +``` + +The response body contains a mapping from receipt IDs to receipts: + +```json +{ + "data": { + "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": { "status": "ok" }, + "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY": { "status": "ok" } + } +} +``` + +**You must check each push receipt, which may contain information about errors you need to resolve.** For example, if a device is no longer eligible to receive notifications, Apple's documentation asks that you stop sending notifications to that device. The push receipts will contain information about these errors. + +> **Note:** Even if a receipt says "ok", it doesn't guarantee that the device has received the message; "ok" in a push receipt means that the Android or iOS push notification service successfully received the notification. If the recipient device is turned off, for example, the iOS or Android push notification service will try to deliver the message but the device won't necessarily receive it. + +### Message format + +Each message must be a JSON object with the given fields: + +```javascript +type PushMessage = { + /** + * An Expo push token specifying the recipient of this message. + */ + to: string, + + /** + * A JSON object delivered to your app. It may be up to about 4KiB; the total + * notification payload sent to Apple and Google must be at most 4KiB or else + * you will get a "Message Too Big" error. + */ + data?: Object, + + /** + * The title to display in the notification. Devices often display this in + * bold above the notification body. Only the title might be displayed on + * devices with smaller screens like Apple Watch. + */ + title?: string, + + /** + * The message to display in the notification + */ + body?: string, + + /** + * Time to Live: the number of seconds for which the message may be kept + * around for redelivery if it hasn't been delivered yet. Defaults to 0. + * + * On Android, we make a best effort to deliver messages with zero TTL + * immediately and do not throttle them + * + * This field takes precedence over `expiration` when both are specified. + */ + ttl?: number, + + /** + * A timestamp since the UNIX epoch specifying when the message expires. This + * has the same effect as the `ttl` field and is just an absolute timestamp + * instead of a relative time. + */ + expiration?: number, + + /** + * The delivery priority of the message. Specify "default" or omit this field + * to use the default priority on each platform, which is "normal" on Android + * and "high" on iOS. + * + * On Android, normal-priority messages won't open network connections on + * sleeping devices and their delivery may be delayed to conserve the battery. + * High-priority messages are delivered immediately if possible and may wake + * sleeping devices to open network connections, consuming energy. + * + * On iOS, normal-priority messages are sent at a time that takes into account + * power considerations for the device, and may be grouped and delivered in + * bursts. They are throttled and may not be delivered by Apple. High-priority + * messages are sent immediately. Normal priority corresponds to APNs priority + * level 5 and high priority to 10. + */ + priority?: 'default' | 'normal' | 'high', + + // iOS-specific fields + + /** + * A sound to play when the recipient receives this notification. Specify + * "default" to play the device's default notification sound, or omit this + * field to play no sound. + * + * Note that on apps that target Android 8.0+ (if using `expo build`, built + * in June 2018 or later), this setting will have no effect on Android. + * Instead, use `channelId` and a channel with the desired setting. + */ + sound?: 'default' | null, + + /** + * Number to display in the badge on the app icon. Specify zero to clear the + * badge. + */ + badge?: number, + + // Android-specific fields + + /** + * ID of the Notification Channel through which to display this notification + * on Android devices. If an ID is specified but the corresponding channel + * does not exist on the device (i.e. has not yet been created by your app), + * the notification will not be displayed to the user. + * + * If left null, a "Default" channel will be used, and Expo will create the + * channel on the device if it does not yet exist. However, use caution, as + * the "Default" channel is user-facing and you may not be able to fully + * delete it. + */ + channelId?: string +} +``` + +### Response format + +The response is a JSON object with two optional fields, `data` and `errors`. If there is an error with the entire request, the HTTP status code will be 4xx or 5xx and `errors` will be an array of error objects (usually just one): + +```json +{ + "errors": [{ + "code": "INTERNAL_SERVER_ERROR", + "message": "An unknown error occurred." + }] +} +``` + +If there are errors that affect individual messages but not the entire request, the HTTP status code will be 200, the `errors` field will be empty, and the `data` field will contain push tickets that describe the errors: + +```json +{ + "data": [{ + "status": "error", + "message": "\\\"ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]\\\" is not a registered push notification recipient", + "details": { + "error": "DeviceNotRegistered" + } + }, { + "status": "ok", + "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" + }] +} +``` + +> **Note:** You should check the ticket for each notification to determine if there was a problem delivering it to Expo. In particular, **do not assume a 200 HTTP status code means your notifications were sent successfully**; the granularity of push notification errors is finer than that of HTTP statuses. + +The HTTP status code will be 200 also if all of the messages were successfully delivered to Expo and enqueued to be delivered to the iOS and Android push notification services. + +Successful push receipts, and some types of failed ones, will contain an "id" field with the ID of a receipt to fetch later. + +### Receipt request format + +Each receipt request must contain a field named "ids" that is an array of receipt IDs: + +```javascript +{ + "ids": string[] +} +``` + +### Receipt response format + +The response format for push receipts is similar to that of push tickets; it is a JSON object with two optional fields, `data` and `errors`. If there is an error with the entire request, the HTTP status code will be 4xx or 5xx and `errors` will be an array of error objects. + +If there are errors that affected individual notifications but not the entire request, the HTTP status code will be 200, the `errors` field will be empty, and the `data` field will be a JSON object whose keys are receipt IDs and values are corresponding push receipts. If there is no push receipt for a requested receipt ID, the mapping won't contain that ID. This is an example response: + +```json +{ + "data": { + "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": { + "status": "error", + "message": "The Apple Push Notification service failed to send the notification", + "details": { + "error": "DeviceNotRegistered" + } + }, + "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY": { + "status": "ok" + } + } +} +``` + +> **Note:** You should check each receipt to determine if there was an issue delivering the notification to the Android or iOS push notification service. In particular, **do not assume a 200 HTTP status code means your notifications were sent successfully**; the granularity of push notification errors is finer than that of HTTP statuses. + +The HTTP status code will be 200 also if all of the messages were successfully delivered to the Android and iOS push notification services. + +**Important:** in particular, look for an `details` object with an `error` field inside both push tickets and push receipts. If present, it may be one of these values: `DeviceNotRegistered`, `MessageTooBig`, `MessageRateExceeded`, and `InvalidCredentials`. You should handle these errors like so: + +- `DeviceNotRegistered`: the device cannot receive push notifications anymore and you should stop sending messages to the corresponding Expo push token. + +- `MessageTooBig`: the total notification payload was too large. On Android and iOS the total payload must be at most 4096 bytes. + +- `MessageRateExceeded`: you are sending messages too frequently to the given device. Implement exponential backoff and slowly retry sending messages. + +- `InvalidCredentials`: your push notification credentials for your standalone app are invalid (ex: you may have revoked them). Run `expo build:ios -c` to regenerate new push notification credentials for iOS. + +If Expo couldn't deliver the message to the Android or iOS push notification service, the receipt's details may also include service-specific information. This is useful mostly for debugging and reporting possible bugs to Expo. + +### Expired Credentials + +When your push notification credentials have expired, simply run `expo build:ios -c --no-publish` to clear your expired credentials and generate new ones. The new credentials will take effect within a few minutes of being generated. You do not have to submit a new build! diff --git a/docs/pages/versions/unversioned/guides/routing-and-navigation.md b/docs/pages/versions/unversioned/guides/routing-and-navigation.md new file mode 100644 index 00000000000000..afb84bed9b109f --- /dev/null +++ b/docs/pages/versions/unversioned/guides/routing-and-navigation.md @@ -0,0 +1,16 @@ +--- +title: Routing & Navigation +old_permalink: /versions/v12.0.0/guides/routing-and-navigation.html +previous___FILE: ./using-custom-fonts.md +next___FILE: ./push-notifications.md +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +A "single page app" on the web is not an app with a single screen, that would indeed be useless most of the time; rather, it is an app that does not ask the browser to navigate to a new URL for each new screen. Instead, a "single page app" will use its own routing subsystem (eg: react-router) that decouples the screens that are being displayed from the URL bar. Often it will also update the URL bar too, but override the mechanism that will cause the browser to reload the page entirely. The purpose of this is for the experience to be smooth and "app-like". + +This same concept applies to native mobile apps. When you navigate to a new screen, rather than refreshing the entire app and starting fresh from that screen, the screen is pushed onto a navigation stack and animated into view according to its configuration. + +The library that we recommend to use for routing & navigation in Expo is [React Navigation](https://github.com/react-community/react-navigation). We recommend following the [fundamentals guide](https://reactnavigation.org/docs/en/getting-started.html) in the [React Navigation documentation](https://reactnavigation.org/) to learn more about how to use it. \ No newline at end of file diff --git a/docs/pages/versions/unversioned/guides/setting-up-continuous-integration.md b/docs/pages/versions/unversioned/guides/setting-up-continuous-integration.md new file mode 100644 index 00000000000000..2de09d9783d063 --- /dev/null +++ b/docs/pages/versions/unversioned/guides/setting-up-continuous-integration.md @@ -0,0 +1,467 @@ +--- +title: Setting up Continuous Integration +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Continuous Integration (CI) and Continuous Delivery (CD) are concepts which can help you to build and deploy with confidence. +It's the idea of automating as much as you can, like running tests or creating new releases. + +CI/CD is a relatively broad idea and can get as complex as you can make it. +In this guide, we will create a basic setup for testing (CI) and deployments (CD). +Also, the configuration for Bitbucket Pipelines, Gitlab CI, and Travis CI are provided. +Other CI/CD vendors can be used too; everything is executable through CLI. + +## Test with Jest + +Testing is an essential part of an average CI workflow. +This process gives you the confidence when shipping by running all automated tests on every relevant change. +Without this, you can't be sure if a proposed change breaks the expected behavior of any existing functionality. + +Before we can run the tests, we need to install the dependencies. You can use yarn, npm-install or even the faster npm-ci command. +After this, we can run the tests with Jest. Unfortunately, we can't use the original npm-test script shipped with expo-cli. +This script is designed to start a daemon that watches for file changes and reruns the tests. +In CI environments we need Jest to run the tests once and exit with a (un)successful status code. +Also, it's also a good idea to explicitly tell Jest it is running in a CI environment. +Jest will handle snapshots more strictly. + +To summarize we will set up the CI to run the following two scripts. + +```bash +$ npm ci +$ npx jest --ci +``` + +
Travis CI +

+ +```yaml +--- +language: node_js +node_js: + - node + - lts/* +cache: + directories: + - ~/.npm +before_script: + - npm install -g npm@latest +script: + - npm ci + - npx jest --ci +``` + +> Put this into `.travis.yml` in the root of your repository. + +

+ See it in action +
+ +

+
+ +
Gitlab CI +

+ +```yaml +--- +image: node:alpine +cache: + key: ${CI_COMMIT_REF_SLUG} + paths: + - ~/.npm +stages: + - test +before_script: + - npm ci +jest-tests: + stage: test + script: + - npx jest --ci +``` + +> Put this into `.gitlab-ci.yml` in the root of your repository. + +

+ See it in action +
+ +

+
+ +
Bitbucket Pipelines +

+ +```yaml +--- +image: node:alpine +definitions: + caches: + npm: ~/.npm +pipelines: + default: + - step: + name: Test with Jest + caches: + - npm + script: + - npm ci + - npx jest --ci +``` + +> Put this into `bitbucket-pipelines.yml` in the root of your repository. + +

+ See it in action +
+ +

+
+ +### Improving Jest performance + +As you might have noticed already, the tests in CI are a bit slower compared to running them locally. +It's slower because your hardware is more powerful than the CI hardware. +Jest can leverage the use of parallel testing with such equipment. +Also, Some vendors limit the hardware resources or offer "premium" services for more power. +Luckily there is a relatively easy way to improve the speed of Jest; using the power of caching. + +There is no definitive way of telling how much it improves. +Using the expo-cli tabs project as an example, it can speed up by a factor of 4x - 5x. + +
Travis CI +

+ +```yaml +--- +language: node_js +node_js: + - node + - lts/* +cache: + directories: + - ~/.npm + - .jest +before_script: + - npm install -g npm@latest +script: + - npm ci + - npx jest --ci +``` + +> Put this into `.travis.yml` in the root of your repository. + +

+ See it in action +
+ +

+
+ +
Gitlab CI +

+ +```yaml +--- +image: node:alpine +cache: + key: ${CI_COMMIT_REF_SLUG} + paths: + - ~/.npm + - .jest +stages: + - test +before_script: + - npm ci +jest-tests: + stage: test + script: + - npx jest --ci +``` + +> Put this into `.gitlab-ci.yml` in the root of your repository. + +

+ See it in action +
+ +

+
+ +
Bitbucket Pipelines +

+ +```yaml +--- +image: node:alpine +definitions: + caches: + npm: ~/.npm + jest: .jest +pipelines: + default: + - step: + name: Test with Jest + caches: + - npm + - jest + script: + - npm ci + - npx jest --ci +``` + +> Put this into `bitbucket-pipelines.yml` in the root of your repository. + +

+ See it in action +
+ +

+
+ +## Deploy to Expo + +Now that we have a proper CI workflow in place, we will focus on the Continuous Deployment (CD) part. +In this process, we will make a new build and push it to Expo. +Combined with Over The Air (OTA) updates, this can create a simple but effective CD infrastructure. +Just like the CI part, we first need to install the dependencies. +After this, we need to authenticate at Expo and "publish" a new build. + +### Prepare Expo CLI + +To interact with the Expo API, we need to install the Expo CLI. +You can use an environment with this library preinstalled, or you can add it to the project as a development dependency. +The latter is the easiest way but might increase the installation time. +For vendors that charge you per minute, it might we worth creating a prebuilt environment. + +To install the Expo CLI into your project, you can execute this script. + +```bash +$ npm install --save-dev expo-cli +``` + +### Prepare authentication + +Next, we will configure the publishing step of your application to Expo. +Before we can do this, we need to authenticate as the owner of the app. +This is possible by storing the username or email with the password in the environment. +Every vendor has implemented their storage mechanism for sensitive data like passwords, although they are very similar. +Most vendors make use of environment variables which are "injected" into the environment and scrubbed from the logs to keep it safe. + +To perform the authentication, we will add this script to our configuration: + +```bash +$ npx expo login -u -p +``` + +### Publish new builds + +After having the CLI library and authentication in place, we can finally create the build step. +In this step, we will create a new build and send it to Expo. +It finalizes the whole workflow of creating, testing and shipping your application. + +To create the builds, we will add this script to our configuration: + +```bash +$ npx expo publish --non-interactive +``` + +
Travis CI +

+ +```yaml +--- +language: node_js +node_js: + - node + - lts/* +cache: + directories: + - ~/.npm + - .jest +before_script: + - npm install -g npm@latest +script: + - npm ci + - npx jest --ci +jobs: + include: + - stage: deploy + node_js: lts/* + script: + - npm ci + - npx expo login -u $EXPO_USERNAME -p $EXPO_PASSWORD + - npx expo publish --non-interactive +``` + +> Put this into `.travis.yml` in the root of your repository. + +

+ See it in action +
+ +

+
+ +
Gitlab CI +

+ +```yaml +--- +image: node:alpine +cache: + key: ${CI_COMMIT_REF_SLUG} + paths: + - ~/.npm + - .jest +stages: + - test + - deploy +before_script: + - npm ci +jest-tests: + stage: test + script: + - npx jest --ci +expo-deployments: + stage: deploy + script: + - apk add --no-cache bash + - npx expo login -u $EXPO_USERNAME -p $EXPO_PASSWORD + - npx expo publish --non-interactive +``` + +> Put this into `.gitlab-ci.yml` in the root of your repository. + +

+ See it in action +
+ +

+
+ +
Bitbucket Pipelines +

+ +```yaml +--- +image: node:alpine +definitions: + caches: + npm: ~/.npm + jest: .jest +pipelines: + default: + - step: + name: Test with Jest + caches: + - npm + - jest + script: + - npm ci + - npx jest --ci + - step: + name: Deploy to Expo + deployment: test + caches: + - npm + script: + - apk add --no-cache bash + - npm ci + - npx expo login -u $EXPO_USERNAME -p $EXPO_PASSWORD + - npx expo publish --non-interactive +``` + +> Put this into `bitbucket-pipelines.yml` in the root of your repository. + +

+ See it in action +
+ +

+
+ +
CircleCI +

+ +```yaml +--- +version: 2 +publish: &publish + working_directory: ~/my-app + docker: + - image: circleci/node:10.4.1 + steps: + - checkout + + - run: + name: Installing dependencies + command: npm install + + - run: + name: Login into Expo + command: npx expo login -u $EXPO_USERNAME -p $EXPO_PASSWORD + + - run: + name: Publish to Expo + command: npx expo publish --non-interactive --max-workers 1 --release-channel $EXPO_RELEASE_CHANNEL + +jobs: + publish_to_expo_dev: + environment: + EXPO_RELEASE_CHANNEL: dev + <<: *publish + + publish_to_expo_prod: + environment: + EXPO_RELEASE_CHANNEL: default + <<: *publish + +workflows: + version: 2 + my_app: + jobs: + - publish_to_expo_dev: + filters: + branches: + only: development + - publish_to_expo_prod: + filters: + branches: + only: master +``` + +> Put this into `.circleci/config.yml` in the root of your repository. + +

+
+ +## Next steps + +CI and CD are concepts which are far from fully covered in this guide. +The best thing you can do to get familiar with these subjects is to make stuff yourself. +Here are some extra links that might help you further. + +### Useful subjects + +- [Release channels](../../distribution/release-channels/) +- [Building standalone apps](../../distribution/building-standalone-apps/) +- [Configuring OTA Updates](../configuring-ota-updates/) + +### Official documentation CI/CD vendors + +- [Gitlab CI](https://docs.gitlab.com/ce/ci/) +- [Travis CI](https://docs.travis-ci.com/) +- [Bitbucket Pipelines](https://confluence.atlassian.com/bitbucket/build-test-and-deploy-with-pipelines-792496469.html) + +### Extra tutorials + +- [Setting up Expo and Bitbucket Pipelines](https://blog.expo.io/setting-up-expo-and-bitbucket-pipelines-8995ef036a18) + +### Example repositories from this guide + +- [Github](https://github.com/bycedric/expo-guide-ci) +- [Gitlab](https://gitlab.com/byCedric/expo-guide-ci) +- [Bitbucket](https://bitbucket.org/byCedric/expo-guide-ci) diff --git a/docs/pages/versions/unversioned/guides/splash-screens.md b/docs/pages/versions/unversioned/guides/splash-screens.md new file mode 100644 index 00000000000000..679e483ea0ca3b --- /dev/null +++ b/docs/pages/versions/unversioned/guides/splash-screens.md @@ -0,0 +1,110 @@ +--- +title: Create a Splash Screen +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +A splash screen, also known as a launch screen, is the first screen that a user sees when opening your app, and it stays visible while the app is loading. You can control when the splash screen disappears by using the [AppLoading](../../sdk/app-loading/) component or [SplashScreen module](../../sdk/splash-screen/). + +## Customize the splash screen for your app + +The default splash screen is a blank white screen. This might work for you, if it does, you're in luck! If not, you're also in luck because it's quite easy to customize using `app.json` and the `splash` key. Let's walk through it. + +### Make a splash image + +The [iOS Human Interface Guidelines](https://developer.apple.com/ios/human-interface-guidelines/icons-and-images/launch-screen/) list the static launch image sizes. I'll go with `1242` pixels wide and `2436` pixels tall -- this is the width of the iPhone 8 Plus (the widest iPhone) and the height of the iPhone X (the tallest iPhone). Expo will resize the image for you depending on the size of the device, and we can specify the strategy used to resize the image with `splash.resizeMode`. + +Android screen sizes vary greatly with the massive variety of devices on the market. One strategy to deal with this is to look at the most common resolutions and design around that - [you can see some statistics on this published by Unity here](https://hwstats.unity3d.com/mobile/display-android.html). Given that we can resize and crop our splash image automatically, it looks like we can stick with our dimensions, as long as we don't depend on the splash image fitting the screen exactly. This is convenient because we can use one splash image for both iOS and Android - less for you to read in this guide and less work for you to do. + +You can work off of [this Sketch template](https://github.com/expo/files/blob/b264c7f7bf2cacfbdb45640063988ab61dfbbe23/splash-template.sketch?raw=true) if you like. I did, and I changed the background color to a faint yellow and put a Noodle emoji in the middle. It's worth noting that the splash image supports transparency, although we didn't use it here. + +![](/static/images/splash-example.png) + +Export the image as a PNG and put it in your project directory. I'll assume it's in the `assets` directory and named `splash.png`. + +### `splash.image` + +Open your `app.json` and add the following inside of the `"expo"` field: + +``` +"splash": { + "image": "./assets/splash.png" +} +``` + +Now re-open the Expo client and open your app, and you should see your beautiful splash screen. There may be a delay before it shows up, see ["Differences between environments" below](#differences-between-environments) for more information on that. + +> **Note**: It's required to close and re-open the Expo client app on iOS in order to see changes to the splash screen in the manifest. This is a known issue that we are working to resolve. On Android, you need to press the refresh button from the notification drawer. + +### `splash.backgroundColor` + +If you set a background color other than white for your splash image, you may see white border around it. This is due to the `splash.resizeMode` property (which we will discuss shortly) and the default background color, which is `#ffffff` (white). Let's resolve this by setting the `splash.backgroundColor` to be the same as our splash image background color. + +``` +"splash": { + "image": "./assets/splash.png", + "backgroundColor": "#FEF9B0" +} +``` + +![backgroundColor Example](/static/images/backgroundColor-noodles.png) + +### `splash.resizeMode` + +Any splash image that you provide will be resized to maintain its aspect ratio and to fit the resolution of the user's device. There are two strategies that can be used for resizing: `contain` (default) and `cover`. In both cases, the splash image is within the splash screen. These work the same as the React Native `` component's `resizeMode` style equivalents, as demonstrated in the following diagram. + +![resizeMode](/static/images/resizeMode.png) + +Applying this to our noodles example, let's remove the `backgroundColor` and try it out: + +``` +"splash": { + "image": "./assets/splash.png", + "resizeMode": "cover" +} +``` + +![resizeMode Example](/static/images/resizeMode-noodles.png) + +Notice that in the last example, we stretched the image to fill the entire width, while maintaining the aspect ratio, and so the noodles emoji ended up being larger than it was when `resizeMode` was set to `contain`. If you are still unclear about the difference between contain and cover, [this blog post describes precisely what they mean](http://blog.vjeux.com/2013/image/css-container-and-cover.html). + +### Customizing the configuration for iOS and Android + +Any of the splash options can be configured on a per-platform basis by nesting the configuration under the `android` or `ios` keys within `app.json` (the same as how you would customize an icon for either platform). In addition to this, certain configuration options are only available on iOS or Android. + +- On iOS, you can set [ios.splash.tabletImage](../../workflow/configuration/#tabletimage) if you would like to have a different splash image on iPads. +- On Android, you can set splash images for [different device DPIs](../../workflow/configuration/#ldpi), from `ldpi` to `xxxhdpi`. + +### Using `AppLoading` and/or `SplashScreen` + +As long as `AppLoading` is the only component rendered in your application, your splash screen will remain visible. We recommend using `AppLoading` while caching assets or fetching any data from `AsyncStorage` to set the app up. However, if you want to control the moment of splash screen visibility change use `SplashScreen`. + +Read more about [AppLoading](../../sdk/app-loading/) and [SplashScreen](../../sdk/splash-screen/). + +### Differences between environments + +Your app can be opened from the Expo client or in a standalone app, and it can be either published or in development. There are slighty differences in the splash screen behavior between these environments. + +![](https://media.giphy.com/media/l378l98EI0VQdwRzy/giphy.gif) + +- **On the left**, we are in the Expo client and loading an app that is currently in development. Notice that on the bottom of the splash screen you see an information bar that shows information relevant to preparing the JavaScript and downloading it to the device. We see an orange screen before the splash image appears, because the background color is set immediately but the image needs to be downloaded. +- **In the middle**, we are in the Expo client and we are loading a published app. Notice that again the splash image does not appear immediately. +- **On the right**, we are in a standalone app. Notice that the splash image appears immediately. + +### Ejected ExpoKit apps + +If you run `expo eject` (choosing the ExpoKit option) on iOS and your app already uses the splash API, the resulting ExpoKit project will contain an Interface Builder launch screen file configured correctly for your app. After this, if you want to make changes to your app's splash screen, just edit the Interface Builder file directly. + +For people who run `expo eject` without the splash API, we add `isSplashScreenDisabled: YES` in your EXShell plist (iOS). If you later decide to use a splash screen in your ejected iOS project, add an Interface Builder file called `LaunchScreen` to your Xcode project, and delete this key from the plist. + +### Known issues + +The following exists are known to us and will be resolved shortly. + +- iOS splash screen status bar is white in standalone apps but dark in Expo client. It should be dark in standalone apps by default too, and also it should be customizable. + +### Migrating from the `loading` API + +The `loading` API is deprecated as of SDK 22 and has a strictly worse user experience, so we recommend you change over to `splash` as soon as you have time - the `loading` API will be removed in favor of `splash` in SDK 25. diff --git a/docs/pages/versions/unversioned/guides/testing-on-devices.md b/docs/pages/versions/unversioned/guides/testing-on-devices.md new file mode 100644 index 00000000000000..df86c579d8ca53 --- /dev/null +++ b/docs/pages/versions/unversioned/guides/testing-on-devices.md @@ -0,0 +1,23 @@ +--- +title: Testing on physical devices +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +The best way to interactively test and verify the behavior and feel of your app as you change code is by loading it in the Expo Client App, as described in other guides. + +There are several ways to get the client app into a test environment. + +## Install Expo Client App from a device's App Store + +This is the simplest and easiest way, and the one we recommend for all developers. + +## Build Expo Client App on your computer and side-load it onto a device + +[The client apps are open-source](https://github.com/expo/expo), and their readme contains instructions on how to compile them locally and install them onto devices attached to your computer by a USB cable. + +## Run Expo Client App on your computer in a device Emulator/Simulator + +[The client apps github repository](https://github.com/expo/expo) also includes instruction on how to build and run the iOS Client App in the Xcode Device Simulator, and the Android Client App in the Android Studio Device Emulator. diff --git a/docs/pages/versions/unversioned/guides/using-clojurescript.md b/docs/pages/versions/unversioned/guides/using-clojurescript.md new file mode 100644 index 00000000000000..4d571fba55062f --- /dev/null +++ b/docs/pages/versions/unversioned/guides/using-clojurescript.md @@ -0,0 +1,141 @@ +--- +title: Using ClojureScript +old_permalink: /versions/v12.0.0/guides/using-clojurescript.html +previous___FILE: ./upgrading-expo.md +next___FILE: ./using-firebase.md +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +## Quickstart + +If you're already convinced about ClojureScript and Expo and know what to do once you have figwheel running, you can just read this section. Otherwise, we encourage you to read the entire guide. + +```javascript +lein new expo your-project + +cd your-project && yarn install + +lein figwheel + +# Now in a new tab, open the project in a simulator +expo start --ios +``` + +> **Note:** This guide was written by [@tiensonqin](https://github.com/tiensonqin), feel free to reach out to him on the [Expo Slack](http://slack.expo.io/) if you have questions! + +## Why Clojurescript? + +- First-class immutable data structures +- Minimizing state and side-effects +- Practicality and pragmatism are always core values of ClojureScript +- Lisp! +- Great JavaScript interoperability + +## Why on Expo? + +It all begins with a [Simple Made Easy](https://www.infoq.com/presentations/Simple-Made-Easy) design choice: **you don't write native code**. + +- You only write ClojureScript or JavaScript. +- You don't have to install or use Xcode or Android Studio or deal with any of the platform specific configuration and project files. +- Much easier to upgrade when there is no native code involved -- React Native JavaScript APIs are relatively stable compared to the native side. Expo will take care of upgrading the native modules and React Native versions, you only need to upgrade your ClojureScript or JavaScript code. +- You can write iOS apps on Linux or Windows (provided that you have an iPhone to test it with). +- It's dead simple to continually share your apps. Once you published your app, you got a link. It is up to you to share the link. + +## 1. Create an Expo project + +```javascript +# Default to use Reagent / Re-frame +lein new expo your-project + +# Or Om Next +lein new expo your-project +om + +cd your-project && yarn install +``` + +## 2. Connect to a REPL + +### CLI REPL + +```javascript +lein figwheel +``` + +### Emacs REPL + +1. Invoke cider-jack-in. +2. Run `(start-figwheel)` in the connected REPL. + +### [Cursive](https://cursive-ide.com/) REPL + +The first time you connect to the repl, you'll need to create a Leiningen nREPL Configuration unless you have one already. + +1. Click `Run->Edit` configurations. +2. Click the `+` button at the top left and choose Clojure REPL. +3. Choose a `Local REPL`. +4. Enter a name in the Name field (e.g. "REPL"). +5. Choose the radio button `Use nREPL with Leiningen`. +6. Click the `OK` button to save your REPL config. + +Once this is done, you can connect to the REPL. + +In Intellij make sure your REPL config is selected and click the green **play** button to start your REPL. + +Run `(start-figwheel)` in the connected REPL. + +## 3. Start Expo server + +### Using Expo CLI + +```javascript +# Install Expo CLI if you have not already +npm install -g expo-cli + +# Connect to iOS simulator +expo start --ios + +# Or connect to Android devices or simulators +expo start --android +``` + +For more information, see [Expo CLI](../../workflow/expo-cli/). + +## 4. Publish your app + +```javascript +# Generate main.js +lein prod-build + +expo publish +``` + +This will publish your app to a persistent URL on Expo, for example: + +## FAQ + +### How do I add custom native modules? + +See [How do I add custom native code to my Expo project?](../../introduction/faq/#faq). + +### Does it support Google Closure advanced compilation? + +It's still experimental, but it already works for multiple projects. + +### Does it support source maps? + +Yes. + +### Can I use npm modules? + +React Native uses JavascriptCore, so modules using built-in node like stream, fs, etc wont work. Otherwise, you can just require like: `(js/require "SomeModule")`. + +### Do I need to restart the REPL after adding new Javascript modules or assets? + +No, you do need to reload Javascript. To do that, select **Reload** from the Developer Menu. You can also press `⌘ + R` in the iOS Simulator, or press `R` twice on Android emulators. + +### Will it support Boot? + +Not currently, but we are working on it. diff --git a/docs/pages/versions/unversioned/guides/using-custom-fonts.md b/docs/pages/versions/unversioned/guides/using-custom-fonts.md new file mode 100644 index 00000000000000..c349fba43266ee --- /dev/null +++ b/docs/pages/versions/unversioned/guides/using-custom-fonts.md @@ -0,0 +1,129 @@ +--- +title: Using Custom Fonts +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Both iOS and Android come with their own set of platform fonts but if you want to inject some more brand personality into your app, a well picked font can go a long way. In this guide we'll walk you through adding a custom font to your Expo app. We'll use [Open Sans](https://fonts.google.com/specimen/Open+Sans) from [Google Fonts](https://fonts.google.com/) in the example, and the process is identical for any other font, so feel free to adapt it to your use case. Before proceeding, go ahead and download [Open Sans](https://fonts.google.com/specimen/Open+Sans) + +## Starting code + +First let's start with a basic "Hello world!" app. Create a new project with `expo init` and change `App.js` to the following: + +```javascript +import React from 'react'; +import { + Text, + View, +} from 'react-native'; + +export default class App extends React.Component { + render() { + return ( + + + Hello, world! + + + ); + } +} +``` + +Try getting this basic app running before playing with Open Sans, so you can get any basic setup issues out of the way. + +## Downloading the font + +Take the Open Sans zipfile that you downloaded, extract it and copy `OpenSans-Bold.ttf` into the assets directory in your project. The location we recommend is `your-project/assets/fonts`. + +## Loading the font in your app + +To load and use fonts we will use the [Expo SDK](../../sdk/), which comes pre-installed when you create a new Expo project, but if for some reason you don't have it, you can install with `npm install --save expo` in your project directory. Add the following `import` in your application code: + +```javascript +import { Font } from 'expo'; +``` + +The `expo` library provides an API to access native functionality of the device from your JavaScript code. `Font` is the module that deals with font-related tasks. First, we must load the font from our assets directory using [`Expo.Font.loadAsync()`](../../sdk/font/#exponentfontloadasync "Expo.Font.loadAsync"). We can do this in the [componentDidMount()](https://facebook.github.io/react/docs/component-specs.html#mounting-componentdidmount) lifecycle method of the `App` component. Add the following method in `App`: Now that we have the font files saved to disk and the Font SDK imported, let's add this code: + +```javascript +export default class App extends React.Component { + componentDidMount() { + Font.loadAsync({ + 'open-sans-bold': require('./assets/fonts/OpenSans-Bold.ttf'), + }); + } + + // ... +} +``` + +This loads Open Sans Bold and associates it with the name `'open-sans-bold'` in Expo's font map. Now we just have to refer to this font in our `Text` component. + +> **Note:** Fonts loaded through Expo don't currently support the `fontWeight` or `fontStyle` properties -- you will need to load those variations of the font and specify them by name, as we have done here with bold. + +## Using the font in a `Text` component + +With React Native you specify fonts in `Text` components using the `fontFamily` style property. The `fontFamily` is the key that we used with `Font.loadAsync`. + +```javascript + + Hello, world! + +``` + +On next refresh the app seems to still not display the text with Open Sans Bold. You will see that it is still using the default system font. The problem is that [`Expo.Font.loadAsync()`](../../sdk/font/#exponentfontloadasync "Expo.Font.loadAsync") is an asynchronous call and takes some time to complete. Before it completes, the `Text` component is already rendered with the default font since it can't find the `'open-sans-bold'` font (which hasn't been loaded yet). + +## Waiting for the font to load before rendering + +We need a way to re-render the `Text` component when the font has finished loading. We can do this by keeping a boolean value `fontLoaded` in the `App` component's state that keeps track of whether the font has been loaded. We render the `Text` component only if `fontLoaded` is `true`. + +First we initialize `fontLoaded` to false in the `App` class constructor: + +```javascript +class App extends React.Component { + state = { + fontLoaded: false, + }; + + // ... +} +``` + +Next, we must set `fontLoaded` to `true` when the font is done loading. [`Expo.Font.loadAsync()`](../../sdk/font/#exponentfontloadasync "Expo.Font.loadAsync") returns a `Promise` that is fulfilled when the font is successfully loaded and ready to use. So we can use [async/await](https://blog.getexponent.com/react-native-meets-async-functions-3e6f81111173) with `componentDidMount()` to wait until the font is loaded, then update our state. + +```javascript +class App extends React.Component { + async componentDidMount() { + await Font.loadAsync({ + 'open-sans-bold': require('./assets/fonts/OpenSans-Bold.ttf'), + }); + + this.setState({ fontLoaded: true }); + } + + // ... +} +``` + +Finally, we want to only render the `Text` component if `fontLoaded` is `true`. We can do this by replacing the `Text` element with the following: + +```javascript + + { + this.state.fontLoaded ? ( + + Hello, world! + + ) : null + } + +``` + +A `null` child element is simply ignored by React Native, so this skips rendering the `Text` component when `fontLoaded` is `false`. Now on refreshing the app you will see that `open-sans-bold` is used. + +This technique is built into the Tabs template for convenience, as you can see [here](https://github.com/expo/new-project-template/blob/d6a440b01801fbeb323265e39a155d969ab6827f/App.js#L19-L37). + +> **Note:** Typically you will want to load your apps primary fonts before the app is displayed to avoid text flashing in after the font loads. The recommended approach is to move the `Font.loadAsync` call to your top-level component. diff --git a/docs/pages/versions/unversioned/guides/using-fcm.md b/docs/pages/versions/unversioned/guides/using-fcm.md new file mode 100644 index 00000000000000..c9ff868555adee --- /dev/null +++ b/docs/pages/versions/unversioned/guides/using-fcm.md @@ -0,0 +1,47 @@ +--- +title: Using FCM for Push Notifications +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Firebase Cloud Messaging is a popular option for delivering push notifications reliably and is required for all new standalone Android apps made with Expo. To set up your Expo Android app to get push notifications using your own FCM credentials, follow this guide closely. + +Note that FCM is not currently available for Expo iOS apps. + +## Client Setup + +1. If you have not already created a Firebase project for your app, do so now by clicking on **Add project** in the [Firebase Console](https://console.firebase.google.com/). + +2. In your new project console, click **Add Firebase to your Android app** and follow the setup steps. **Make sure that the Android package name you enter is the same as the value of `android.package` in your app.json.** + +3. Download the `google-services.json` file and place it in your Expo app's root directory. + +4. In your app.json, add an `android.googleServicesFile` field with the relative path to the `google-services.json` file you just downloaded. If you placed it in the root directory, this will probably look like + +```javascript +{ + ... + "android": { + "googleServicesFile": "./google-services.json", + ... + } +} +``` + +Finally, make a new build of your app by running `expo build:android`. + +## Uploading Server Credentials + +In order for Expo to send notifications from our servers using your credentials, you'll need to upload your secret server key. You can find this key in the Firebase Console for your project: + +1. At the top of the sidebar, click the **gear icon** to the right of **Project Overview** to go to your project settings. + +2. Click on the **Cloud Messaging** tab in the Settings pane. + +3. Copy the token listed next to **Server key**. + +4. Run `expo push:android:upload --api-key `, replacing `` with the string you just copied. We'll store your token securely on our servers, where it will only be accessed when you send a push notification. + +That's it -- users who run this new version of the app will now receive notifications through FCM using your project's credentials. You just send the push notifications as you normally would (see [guide](../../guides/push-notifications#2-call-expos-push-api-with-the)). We'll take care of choosing the correct service to send the notification. diff --git a/docs/pages/versions/unversioned/guides/using-firebase.md b/docs/pages/versions/unversioned/guides/using-firebase.md new file mode 100644 index 00000000000000..d4f8dc6389a887 --- /dev/null +++ b/docs/pages/versions/unversioned/guides/using-firebase.md @@ -0,0 +1,172 @@ +--- +title: Using Firebase +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +Firebase Database is a popular NoSQL cloud database that allows developers realtime synchronization of live data. With multi-platform support, synchronizing data between users and clients is pretty seamless, but it can also be used more generally as a generic persistent NoSQL data backing if you don't care about realtime updates. It has a very flexible rules syntax to allow minute control over data access as well. + +Luckily, the Firebase JavaScript SDK starting from version 3.1+ has almost full support for React Native, so adding it to our Expo app is super easy. The one caveat covered later in this guide is that the user login components typically provided by the Firebase SDKs will **not** work for React Native, and thus we will have to work around it. + +See [firebase.google.com/docs/database](https://firebase.google.com/docs/database) for more general information and the [official Firebase blog post announcing React Native compatibility](https://firebase.googleblog.com/2016/07/firebase-react-native.html) + +> **Note:** This guide only covers Firebase Realtime Database, and not the other services under the larger Google Firebase umbrella. Firebase Cloud Storage is currently not supported, but we are [working on upstreaming a Blob implementation](https://github.com/facebook/react-native/issues/11103) to React Native that would make this possible. For more background on why other Firebase services are not supported, please read [Brent Vatne's response on Canny](https://expo.canny.io/feature-requests/p/full-native-firebase-integration) + +## 1. Firebase SDK Setup + +First we need to setup a Firebase Account and create a new project. We will be using the JavaScript SDK provided by Firebase, so pull it into your Expo project. + +`npm install --save firebase`. + +The Firebase console will provide you with an api key, and other identifiers for your project needed for initialization. [firebase-web-start](https://firebase.google.com/docs/database/web/start) has a detailed description of what each field means and where to find them in your console. + +```javascript +import * as firebase from 'firebase'; + +// Initialize Firebase +const firebaseConfig = { + apiKey: "", + authDomain: "", + databaseURL: "", + storageBucket: "" +}; + +firebase.initializeApp(firebaseConfig); +``` + +### Temporarily Bypass Default Security Rules + +By default Firebase Database has a security rule setup such that all devices accessing your data must be authenticated. We obviously haven't setup any authentication yet, so we can disable it for now while we setup the rest of our app. + +Go into the Firebase console for Database, and under the Rules tab you should see a default set of rules already provided for you. Change the rules to: + +```javascript +{ + "rules": { + ".read": true, + ".write": true + } +} +``` + +[See Sample Firebase Rules](https://firebase.google.com/docs/database/security/quickstart#sample-rules) for good sets of rules for your data, including unauthenticated. + +> **Note** It is important to note that this is temporary for development, and these rules should be thoroughly assessed before releasing an application. + +## 2. Storing Data and Receiving Updates + +Storing data through Firebase can be pretty simple. Imagine we're creating a game where highscores are stored in Firebase for everyone to see. We could create a users bucket in our data that is referenced by each user. Setting their highscore would be straightforward. + +```javascript +function storeHighScore(userId, score) { + firebase.database().ref('users/' + userId).set({ + highscore: score + }); +} +``` + +Now let's say we wanted another client to listen to updates to the high score of a specific user. Firebase allows us to set a listener on a specific data reference and get notified each time there is an update to the data. In the example below, every time a highscore is updated for the given user, it will print it to console. + +```javascript +setupHighscoreListener(userId) { + firebase.database().ref('users/' + userId).on('value', (snapshot) => { + const highscore = snapshot.val().highscore; + console.log("New high score: " + highscore); + }); +} +``` + +## 3. User Authentication + +This was all pretty simple and works fairly out of the box for what Firebase JavaScript SDK provides. There is one caveat however. We skipped the authentication rules for simplicity at the beginning. Firebase SDKs provide authentication methods for developers, so they don't have to reimplement common login systems such as Google or Facebook login. + +This includes UI elements in the Web, Android, and iOS SDK versions for Firebase, however, these UI components do not work with React Native and **should not** be called. Thankfully, Firebase gives us ways to authenticate our data access given that we provide user authentication ourselves. + +### Login Methods + +We can choose different login methods that make sense to our application. The login method choice is orthogonal to the Firebase Database access, however, we do need to let Firebase know how we have setup our login system such that it can correctly assign authentication tokens that match our user accounts for data access control. You can use anything you want, roll your own custom login system, or even forego it altogether if all your users can have unrestricted access. + +### Facebook Login + +A common login system many developers opt for is a simple Facebook login that users are already familiar with. Expo provides a great Facebook login component already, so we just need to plug that in. + +See the Facebook section of our docs for information on how to set this up. This works just as well with Google and [several others](https://firebase.google.com/docs/reference/android/com/google/firebase/auth/AuthCredential#getProvider()). + +### Tying Sign-In Providers with Firebase + +Once you have added Facebook login to your Expo app, we need to adjust the Firebase console to check for it. Under the Authentication section in the console in the Sign-In Method tab, enable Facebook as a sign-in provider. + +You can add whichever provider makes sense for you, or even add multiple providers. We will stick with Facebook for now since we already have a simple drop-in Expo component already built. + +### Reenable Data Access Security Rule + +We need to re-enable the Data Security Rule in our Firebase console again to check for user authentication. This time our rules will be slightly more complicated. + +For our example, let's say we want everyone to be able to read the high score for any user, but we want to restrict writes to only the user who the score belongs to. You wouldn't want anyone overwriting your highscore, would you? + +```javascript +{ + "rules": { + "users": { + "$uid": { + ".read": true, + ".write": "$uid === auth.uid" + } + } + } +} +``` + +### Listening for Authentication + +We are now ready to connect the Facebook login code with our Firebase Database implementation. + +```javascript +firebase.initializeApp(config); + +// Listen for authentication state to change. +firebase.auth().onAuthStateChanged((user) => { + if (user != null) { + console.log("We are authenticated now!"); + } + + // Do other things +}); + +async function loginWithFacebook() { + const { type, token } = await Expo.Facebook.logInWithReadPermissionsAsync( + '', + { permissions: ['public_profile'] } + ); + + if (type === 'success') { + // Build Firebase credential with the Facebook access token. + const credential = firebase.auth.FacebookAuthProvider.credential(token); + + // Sign in with credential from the Facebook user. + firebase.auth().signInWithCredential(credential).catch((error) => { + // Handle Errors here. + }); + } +} +``` + +The Facebook login method is similar to what you see in the Facebook login guide, however, the token we receive from a successful login can be passed to the Firebase SDK to provide us with a Firebase credential via `firebase.auth.FacebookAuthProvider.credential`. We can then sign-in with this credential via `firebase.auth().signInWithCredential`. + +The `firebase.auth().onAuthStateChanged` event allows us to set a listener when the authentication state has changed, so in our case, when the Facebook credential is used to successfully sign in to Firebase, we are given a user object that can be used for authenticated data access. + +### Authenticated Data Updates + +Now that we have a user object for our authenticated user, we can adapt our previous `storeHighScore()` method to use the uid of the user object as our user reference. Since the `user.uid`'s are generated by Firebase automatically for authenticated users, this is a good way to reference our users bucket. + +```javascript +function storeHighScore(user, score) { + if (user != null) { + firebase.database().ref('users/' + user.uid).set({ + highscore: score + }); + } +} +``` diff --git a/docs/pages/versions/unversioned/guides/using-graphql.md b/docs/pages/versions/unversioned/guides/using-graphql.md new file mode 100644 index 00000000000000..8b4b60dfe88c9d --- /dev/null +++ b/docs/pages/versions/unversioned/guides/using-graphql.md @@ -0,0 +1,377 @@ +--- +title: Using GraphQL +--- + +import withDocumentationElements from '~/components/page-higher-order/withDocumentationElements'; + +export default withDocumentationElements(meta); + +## Overview + +[GraphQL](http://graphql.org/) is a *query language* for APIs. It enables declarative data fetching and thus ties in perfectly with React/React Native as a declarative framework for building user interfaces. GraphQL can either complement or entirely replace the usage of REST APIs. + +The main difference between REST and GraphQL is that RESTful APIs have *multiple endpoints* that return *fixed data structures* whereas a GraphQL server only exposes a *single endpoint* and returns *flexible data structures*. This works because a client that needs data from the server also submits its precise data requirements in each request which allows the server to tailor the response exactly according to the client’s needs. + +You can learn more about the differences between GraphQL and REST [here](https://www.howtographql.com/basics/1-graphql-is-the-better-rest/). To get a high-level overview and understand more about the architectural use cases of GraphQL, take a look at [this](https://www.howtographql.com/basics/3-big-picture/) article. + +GraphQL has a rapidly growing community. To stay up-to-date about everything that’s happening in the GraphQL ecosystem, check out these resources: + +* [GraphQL Weekly](https://www.graphqlweekly.com/): Weekly newsletter about GraphQL +* [GraphQL Radio](https://www.graphqlradio.com/): Podcast discussing real-world use cases of GraphQL +* [GraphQL Europe](https://www.graphql-europe.org/): Europe's biggest GraphQL conference +* [Prisma blog](https://blog.graph.cool/): Technical deep dives and tutorials all around GraphQL development + +For an in-depth learning experience, visit the [How to GraphQL](https://www.howtographql.com/) fullstack tutorial website. + +## Communicating with a GraphQL API + +In this section, we’ll explain the core concepts you need to know when working with a GraphQL API. + +### Fetching data with GraphQL queries + +When an application needs to retrieve data from a GraphQL API, it has to send a _query_ to the server in which it specifies the data requirements. Most GraphQL servers accept only HTTP POST requests where the query is put into the *body* of the request. Note however that GraphQL itself is actually *transport layer agnostic*, meaning that the client-server communication could also happen using other networking protocols than HTTP. + +Here’s an example query that a client might send in an Instagram-like application: + +```graphql +query { + feed { + id + imageUrl + description + } +} +``` + +The keyword `query` in the beginning expresses the *operation type*. Besides `query`, there are two more operation types called `mutation` and `subscription`. Note that the default operation type of a request is in fact `query`, so you might as well remove it from the above request. `feed` is the *root field* of the query and everything that follows is called the *selection set* of the query. + +When a server receives the above query, it will [resolve](https://blog.graph.cool/graphql-server-basics-the-schema-ac5e2950214e#1880) it, i.e. collect the required data, and package up the response in the same format of the query. Here’s what a potential response could look like: + +```json +{ + "data": { + "feed": [ + { + "id": "1", + "description": "Nice Sunset", + "imageUrl": "http://example.org/sunset.png" + }, + { + "id": "2", + "description": "Cute Cats", + "imageUrl": "http://example.org/cats.png" + } + ] + } +} +``` + +The root of the returned JSON object is a field called `data` as defined in the official [GraphQL specification](http://facebook.github.io/graphql/#sec-Data). The rest of the JSON object then contains exactly the information that the client asked for in the query. If the client for example hadn’t included the `imageUrl` in the query’s selection set, the server wouldn’t have included it in its response either. + +In case the GraphQL request fails for some reason, e.g. because the query was malformed, the server will not return the `data` field but instead return an array called `errors` with information about the failure. Notice that it can happen that the server returns both, `data` *and* `errors` . This can occur when the server can only partially resolve a query, e.g. because the user requesting the data only had the access rights for specific parts of the query's payload. + +### Creating, updating and deleting data with GraphQL mutations + +Most of the time when working with an API, you’ll also want to make changes to the data that’s currently stored in the backend. In GraphQL, this is done using so-called *mutations*. A mutation follows the exact same syntactical structure as a query. In fact, it actually also *is* a query in that it combines a write operation with a directly following read operation. Essentially, the idea of a mutation corresponds to the PUT, POST and DELETE calls that you would run against a REST API but additionally allows you to fetch data in a single request. + +Let’s consider an example mutation to create a new post in our sample Instagram app: + +```graphql +mutation { + createPost(description: "Funny Birds", imageUrl: "http://example.org/birds.png") { + id + } +} +``` + +Instead of the `query` operation type, this time we’re using `mutation`. Then follows the *root field*, which in this case is called `createPost`. Notice that all fields can also take arguments, here we provide the post’s `description` and `imageUrl` so the server knows what it should write into the database. In the payload of the mutation we simply specify the `id` of the new post that will be generated on the server-side. + +After the server created the new post in the database, it will return the following sample response to the client: + +```json +{ + "data": { + "createPost": { + "id": "1" + } + } +} +``` + +## The GraphQL schema + +In this section, we'll discuss the backbone of every GraphQL server: The GraphQL schema. + +> For a technical deep dive all around the GraphQL schema, be sure to check out [this](https://blog.graph.cool/graphql-server-basics-the-schema-ac5e2950214e) article. + +### The Schema Definition Language (SDL) + +GraphQL has a [type system](http://graphql.org/learn/schema/#type-system) that’s used to define the capabilities of an API. These capabilities are written down in the GraphQL *schema* using the syntax of the GraphQL [Schema Definition Language](https://blog.graph.cool/graphql-sdl-schema-definition-language-6755bcb9ce51) (SDL). Here’s what the `Post` type from our previous examples looks like: + +```graphql +type Post { + id: ID! + description: String! + imageUrl: String! +} +``` + +The syntax is pretty straightforward. We’re defining a type called `Post` that has three properties, in GraphQL terminology these properties are called _fields_. Each field has a *name* and a *type*. The exclamation point following a type means that this field cannot be `null`. + +### Root types are the entry points for the API + +Each schema has so-called [root types](http://graphql.org/learn/schema/#the-query-and-mutation-types) that define the *entry points* into the API. These are the root types that you can define in your schema: + +* `Query`: Specifies all the queries a GraphQL server accepts +* `Mutation`: Specifies all the mutations a GraphQL server accepts +* `Subscription`: Specifies all the subscriptions a GraphQL server accepts (subscriptions are used for realtime functionality, learn more [here](http://graphql.org/blog/subscriptions-in-graphql-and-relay/)) + +To enable the `feed` query and `createPost` mutation that we saw in the previous examples, you’d have to write the root types as follows: + +```graphql +type Query { + feed: [Post!]! +} + +type Mutation { + createPost(description: String!, imageUrl: String!): Post +} +``` + +You can read more about the core GraphQL constructs [here](https://www.howtographql.com/basics/2-core-concepts/). + +## Getting started with GraphQL + +The first thing you need when getting started with GraphQL is of course a GraphQL server. As GraphQL itself is only a [specification](https://facebook.github.io/graphql/), you can either implement your own server using one of the available [reference implementations](http://graphql.org/code/#server-libraries) or take a shortcut by using a tool like [Apollo Launchpad](https://launchpad.graphql.com/). + +The best way to get started with GraphQL in production is to use [`graphql-yoga`](https://github.com/graphcool/graphql-yoga), a flexible GraphQL server based on Express.js. `graphql-yoga` has a number of compelling features, such as support for [GraphQL Playground](https://github.com/graphcool/graphql-playground) and built-in GraphQL subscriptions for realtime functionality. + +A great way to add a database to your GraphQL server is by using [Prisma](http://prismagraphql.com/). Prisma is an open-source GraphQL query engine that turns your database into a GraphQL API. Thanks to [Prisma bindings](https://github.com/graphcool/prisma-binding), it integrates nicely with your `graphql-yoga` server. + +> To learn how to build a GraphQL server, check out this [tutorial](https://blog.graph.cool/tutorial-how-to-build-a-graphql-server-with-graphql-yoga-6da86f346e68) or watch this 4-min demo [video](https://www.youtube.com/watch?v=20zGexpEitc). + +Since GraphQL servers are commonly implemented with HTTP, you can simply use `fetch` to get started and send queries and mutations to interact with the server. However, when working with GraphQL on the frontend, you’ll usually want to use a [GraphQL client](https://www.howtographql.com/advanced/0-clients/) library. GraphQL clients generally provide handy abstractions and allow you to directly send queries and mutations without having to worry about lower-level networking details. + +There are four major GraphQL clients available at the moment: + +* [Apollo Client](https://www.apollographql.com/client): Community-driven, flexible and powerful GraphQL client that’s easy to understand and has an intuitive API. +* [Relay](https://facebook.github.io/relay/): Facebook’s homegrown GraphQL client that’s heavily optimized for performance and comes with a notable learning curve. +* [Urql](https://github.com/FormidableLabs/urql): Simple GraphQL client for React. +* [graphql-request](https://github.com/graphcool/graphql-request): Simple and lightweight GraphQL client that works in all JavaScript environments and can be used for simple use cases like scripting. + +Apollo, Relay and Urql implement further features like caching, realtime support with GraphQL subscriptions or optimistic UI updates. + +Learn how to integrate with Auth0 social providers in the [expo-auth0-example](https://github.com/graphcool-examples/react-native-graphql/tree/master/authentication-with-expo-and-auth0) repository. + +### Creating your own GraphQL server + +The fastest way to get started with GraphQL is by using a [GraphQL boilerplate](https://github.com/graphql-boilerplates) project for the technology of your choice. GraphQL boilerplates provide the ideal starter kits for your GraphQL-based projects - no matter if backend-only or fullstack. + +To get started, you can use the `graphql create` command (which is similar to `create-react-native-app`). + +First, you need to install the [GraphQL CLI](https://github.com/graphql-cli/graphql-cli): + +```sh +npm install -g graphql-cli +``` + +With the CLI installed, you can run the following command: + +```sh +graphql create myapp +``` + +This will prompt you a list of the available boilerplates. Each technology has a `minimal`, a `basic` and an `advanced` version. + +Choose `minimal` to learn what the most minimal version of a GraphQL server looks like. `basic` boilerplates come with an integrated database (based on Prisma). Finally, the `advanced` boilerplates additionally come with built-in authentication functionality for your users as well as support for realtime subscriptions. + +To skip the interactive prompt, you can also pass the `--boilerplate` (short: `-b`) flag to the `graphql create` command and specify which starter kit you'd like to use. For example: + +```sh +graphql create myapp --boilerplate node-advanced # The `advanced` boilerplate for Node.js +# or +graphql create myapp --boilerplate react-fullstack-basic # The `basic` boilerplate for a fullstack React app +``` + +## Running a practical example with React, Apollo & GraphQL + +If you want to get your hands dirty and learn how to get started with a practical example, check out the [basic](https://github.com/graphql-boilerplates/react-fullstack-graphql/tree/master/basic) boilerplate for a fullstack React application. + +> **Note** There are currently no boilerplate projects for React Native. However, all the code that's used to interact with the GraphQL API from within the React app can be applied in a React Native application in an identical manner! + +Run `graphql create` and specify `react-fullstack-basic` as your target boilerplate: + +```sh +graphql create myapp --boilerplate react-fullstack-basic +``` + +The GraphQL CLI will now fetch the code from the corresponding [GitHub repository](https://github.com/graphql-boilerplates/react-fullstack-graphql/) and run an install [script](https://github.com/graphql-boilerplates/react-fullstack-graphql/blob/master/basic/.install/index.js) to configure everything that's required. + +After having downloaded the code from the repo, the CLI will prompt you to choose where you want to deploy your Prisma database service. To get started quickly, select one of the _development clusters_ (`prisma-eu1` or `prisma-us1`). If you have [Docker](https://www.docker.com/) installed, you can also deploy locally. + +The install script will use the generated endpoint for the Prisma service and connect the GraphQL server with it by insterting it into `src/server/index.js`. + +Once the command has finished, you first need to start the server and second start the React app: + +```sh +cd myapp/server +yarn start +# the server is now running on http://localhost:4000; +# to continue, open a new tab in your terminal +# and navigate back to the root directory +cd .. +yarn start +``` + +The React app is now running on `http://localhost:3000` (the GraphQL server is running on `http://localhost:4000`). + +> To learn about the queries and mutations accepted by the GraphQL API, check out the GraphQL schema that's stored in `server/src/schema.graphql`. + +As an example, here is how the `FeedQuery` component is implemented that displays a list of `Post` elements: + +```js +import React from 'react' +import Post from '../components/Post' +import { graphql } from 'react-apollo' +import gql from 'graphql-tag' + +class FeedPage extends React.Component { + componentWillReceiveProps(nextProps) { + if (this.props.location.key !== nextProps.location.key) { + this.props.feedQuery.refetch() + } + } + + render() { + if (this.props.feedQuery.loading) { + return ( +
+
Loading (from {process.env.REACT_APP_GRAPHQL_ENDPOINT})
+
+ ) + } + + return ( + +

Feed

+ {this.props.feedQuery.feed && + this.props.feedQuery.feed.map(post => ( + this.props.feedQuery.refetch()} + isDraft={!post.isPublished} + /> + ))} + {this.props.children} + + ) + } +} + +const FEED_QUERY = gql` + query FeedQuery { + feed { + id + text + title + isPublished + } + } +` + +export default graphql(FEED_QUERY, { + name: 'feedQuery', // name of the injected prop: this.props.feedQuery... + options: { + fetchPolicy: 'network-only', + }, +})(FeedPage) +``` + +A mutation to create new `Post` elements in performed in the `CreatePage` component: + +```js +import React from 'react' +import { withRouter } from 'react-router-dom' +import { graphql } from 'react-apollo' +import gql from 'graphql-tag' + +class CreatePage extends React.Component { + state = { + title: '', + text: '', + } + + render() { + return ( +
+
+

Create Draft

+ this.setState({ title: e.target.value })} + placeholder="Title" + type="text" + value={this.state.title} + /> +