Setting up Respresso in a Web frontend project

To get started, you need a project in Respresso.
Respresso projects' are designed to be shared across platforms. If your app is implemented for Android or iOS you can use their Respresso project.

Set up a new Web project

  1. Install the Respresso CLI on all the machines you want to use to sync resource files. (Do NOT use the legacy respresso npm package.)
  2. Go to the project dashboard in Respresso and find your project token at the top.
  3. In your project / module directory, run respresso init --token <your project token>. This will automatically create the respresso.json config file based on your project structure. The CLI tries its best to guess your project config, but you might need to customize it manually as Web project structure changes dramatically from framework to framework and from team to team. The respresso.json file should be added to your VCS (aka. Git).
  4. Run respresso sync. This will create the respresso.lock file and download/upload all the requested resource files. For VCS include or ignore dilemmas, see the get started page of the Respresso CLI.
  5. Optionally, add the following npm script to your package.json to execute the sync with the npm run sync command:
{
  "scripts": {
    "sync": "respresso sync",
    // Other scripts...
  }
}

For more info see the NPM Sync page

The Respresso CLI is highly customizable. You can learn more about it in the get started page of the CLI.

Available categories and groups

The following resource categories and groups are supported for Web:

  • Localization: json group for structured json files and jsonflat group for key-value pairs
  • Colors: sass, scss and json
  • Image: web and scss
  • Font: web (Only self-hosted fonts are supported)

All the files will be paced in a respresso directory by default. The CLI might detect your current location for each file type and create the proper config for you, but you can also change it in your resoresso.json config using target overrides.

We know, that this is a limited set of format compared to the large ecosystem of JavaScript frameworks and libraries. We aim to extend Respresso's capabilities when it comes to Web projects. To help us find the proper direction, please let us know which formats you are missing the most at info@respresso.io.

Migrate an existing Web app

  1. Go to your Respresso project and import your resource files in each resource category.
  • Localization: Go to the localization category and import your localizations.
    1. You will need to add a default language.
    2. Drag and drop your default localization json file or select it using the Import button. In the import settings, you may want to change the variable import option.
    3. If you have multiple languages, you need to add them using the Language Management Toolbar
    4. Import each language one by one, by selecting the language from the toolbar, them importing it. Make sure you import it to the proper language!
  • Images: Go to the image category and import your icons and images.
    • Drag and drop your static/images (or the one you use for images) directory or select it with Upload button. You might get some errors for non image files if the directory contains other files. You can ignore them.
    • Once you uploaded the images, you need to press the Save button. The first save will take a while. If you added more than 10 images, it may show an Unknown error due to a timeout, but the save will eventually finish in the background. Just come back in a few minutes and refresh the page.
    • If you use base64 encoded icons in your styles, you can also import your compiled CSS file(s), Respresso will import them. Just drag&drop the css files one-by-one to the image list.
  • Colors: Go to the color category and import your colors. Drag and drop your compiled CSS file or select it using the Import button. You might need to fix the color keys after they are imported.
  1. Set up your project as you would with a new project. Instructions above.
  2. When you run your first respresso sync you might need to confirm some file overrides. For this reason, you must run the first sync from a terminal and not from NPM.
  3. After your sync finishes, your build will need to switch to the new resource files:
  • Localization:
    • The CLI automatically creates a target override for your localizations if it detected the previous ones. You might want to change that override to replace the .respresso.json part in the targetPattern with .json. Alternatively, you can choose to stick to the respresso suffix and load the new files instead.
    • If you use a localization library that supports structured json localizations the json sync group should be used. If you have used a key-value pair, instead of a structured json, you can switch to the jsonflat group in the localization category.
  • Color: You can use the respresso/_respresso-colors.scss file. (If the CLI detected a style directory in your project, you should look there for this file.)
  • Image: You can use the respresso/images.scss file. (If the CLI detected a style directory in your project, you should look there for this file.)
  1. Hurray! Your project is good to go. If you change something in Respresso and run a sync, it will magically appear in your project.

Keep in mind, that importing the same resources from multiple platforms may cause unexpected behaviour. Imports merge the imported resources with the existing ones. (Usually overriding the pre-existing ones.) If you import your Android or iOS resources then import the same ones from your Web project will result in a mixture or the resources unless you named them exactly the same. In that case, the Web version will be used as it was imported later.