Use our CLI with our Sandbox Web-app

Takes you through setting up a Figma file to sync with your own Dittobnb, the sample web-app we used in our demo video.

Once you've gotten your CLI set up, you can use our sandbox web-app to test out syncing text from Ditto directly into development with a real web-app. After this, you'll have the same setup we have in our demo video!

By the end of this tutorial, you'll have a fully functioning Dittobnb web-app pulling text from a Figma file.

Requirements

  • A Ditto account — with either Admin or Editor permissions

  • A locally installed Ditto CLI

  • A Figma account — don't worry, you don't need to be an expert Figma user! Our sample Figma file has got you covered. You just need a Figma account in order to import the text into Ditto.

Creating a Ditto Project

In order to have a project you can pull from with our CLI, you'll have to create a project in Ditto. At the moment, Ditto projects are created by linking and importing text from a Figma file.

Don't worry, we've made a sample Figma file that corresponds with our example web-app!

  1. Duplicate our sample Figma file, Dittobnb.

  2. Import it into Ditto. To match up with our sandbox web-app, you should import all of the frames in the file. For instructions on importing a file to Ditto, click here.

You should now be able to see your new Ditto project in your workspace. We'll come back to this in a bit!

Setting up the sandbox web-app

Our sandbox web-app is a simple React application that mirrors what's contained in the Dittobnb Figma file. To get it set up:

  1. Duplicate the sandbox repo

  2. Run npm start to run the web-app locally

  3. Once it's running, you can head to:

A couple of things to note:

  • The web-app is currently displaying text from /ditto/text.json, which we have preloaded into the repo. Once you set up the CLI with the web-app, it'll overwrite this file with text from your actual project.

  • Our web-app is also set up with our React SDK. You can see it in action in each of the React components in /src/components/.

Setting up your project to sync with the web-app

Now that you've got both the Ditto project and web-app, let's link the two so that changes you make in the Ditto project (or Figma file!) can be pulled directly into development.

  1. Structure your Ditto project to match /ditto/text.json.

    Because the pre-loaded JSON in the repo was generated to from a Ditto project, you'll have to organize your project a bit so that it matches the JSON. Don't worry, you won't have to do this for other projects (aka without a pre-loaded JSON)!

    In the Ditto web-app, create blocks in the project for:

    • Text in the nav bar

    • Text in the Hero

    • Columns of the footer

    You can also refer directly to /ditto/text.json to see the structure of the sample JSON (and the blocks that are set up there). For help creating blocks, click here.

  2. Turn on Developer Mode in the project.

    For help with turning on Developer mode, click here.

  3. Rename or replace IDs.

    At the moment, the web-app front-end fetches specific frames/blocks/texts via IDs provided to the React SDK. In order for it to continue working once you link up the CLI (which replaces the text.json with the real JSON generated from your project), you'll have to either:

    • Rename the IDs in your project to match the ones used in the front-end.

    • OR, replace the ID's given to the React SDK with the real ones from your project.

    You can also do a combination of the two, as long as the project matches how it's referenced in development. Note that this is also a step you don't have to do if you're starting a project from scratch!

  4. Link the CLI.

    In the terminal, navigate to the root of the project repository.

    1. Use the command ditto-cli project, and select the Dittobnb project from the list. Note that this command will only list projects that have Developer Mode turned on.

    2. To pull in text from your actual Ditto project (and replace the text.json in your local directory), use the command ditto-cli pull. You may have to check back on your web-app to see if there are any missing or incorrect IDs.

You're ready to go! 🎉

A couple of things you can try include:

  • Editing in Ditto or Figma, and then doing a ditto-cli pull. All you have to do is refresh the web-app to see the latest copy changes pulled in. Magic!

  • On the /listing page of the web-app, we've left some text items from the mockup out of the web-app. Try and see if you can implement new pieces of text into the web-app!