Skip to content

Snapchat/minis-samples

Repository files navigation

minis-samples

Snap Minis are bite-size utilities made for friends. They’re built with HTML5, so they’re easy to develop. Plus, they work for all Snapchatters, on any kind of device, with no installation required.

This repo contains sample Snap Minis built using Create React App and Typescript. Snap Minis do not need to be built with Create React App or Typescript. Any web framework that bundles the entire application into a single HTML5 bundle can be used.

These samples serve as a guide for developers to quickly get started building their Snap Mini. Please consult our docs if you have any questions not answered in this readme.

Setup

We recommend using yarn for package management.

git clone [email protected]:Snapchat/minis-samples.git
cd minis-samples
yarn

The minimum Snapchat version for these samples is 11.82.

These common commands will work from any mini under minis. For sample, you can cd minis/sample and run yarn start to run the sample mini on your localhost:3000.

yarn start                      # run on localhost:3000
yarn minis:build
yarn minis:release -b <build id>
yarn minis:target -r <release> -u <Snapchat usernames>

The build version and release name is by default $git config --global user.name).${current unix time}`. The build notes are the git hash with the current git user. These can be overridden by passing additional args to snapdev.

yarn minis:build -v <version> -n <notes>
yarn minis:release -b <build id> -n <name>

Minis npm scripts (e.g. minis:build) require snapdev CLI. It can be installed here.

Rapid Development

Rapid development allows changes to a Snap Mini to be instantly reloaded into Snapchat.

  1. Run yarn start. You should see the following
You can now view sample-mini in the browser.

  Local:            http://localhost:3000
  On Your Network:  http://192.168.1.2:3000
  1. Create a rapid development build with that port and URL. The build can sometimes fail if "/" is not added after the port.
yarn minis:build-rapid

That script will add the URL from yarn rapid:host --silent. If that URL is wrong from yarn rapid:host --silent, then run

yarn minis:build-rapid -u <URL from above>

The rapid will be named the rapid.<git username>.<unix time>. It will have the URL as the notes.

  1. Target yourself to that build
yarn minis:release -b <build from before>
yarn minis:target -r <release from before> -u <user name>

Open up Snapchat while you are on that same WiFi network.

If you have an android device, it is possible to remote debug the webview that the Snap Mini is running in.

Additional Resources

For manging network calls, we recommend SWR or React Query with fetch or axios.

We recommend using Chrome with the Chrome debug tools for local debugging.

We recommend using React Router to create a multipage mini.

Important notes:

  • MemoryRouter is required because routers with browser history will refresh the webpage and cause issue with receiving client events on Android
  • The default URL path for Minis when opened is not "/", so use a match all for the Minis' main page (e.g. <Route path="*" element={<MainPage />} />.
  • Swipe actions can be implemented with react-swipeable.

Repo Development

To run any mini, cd into their directory (e.g. cd minis/sample ). Alternatively, all the commands can be run from the root using workspace.

yarn workspace @snapchat/minis-sample start

Husky is set up to lint staged files.

From the top level,

yarn lint                 # run lint
yarn lint:fix             # fix lint

Please read this doc to learn more about the Create React App commands.