Developer Quickstart

We started Raisely as developers wanting a better way to build fundraising campaigns for the people and planet, so our developer experience and the customisation options you have as a developer in Raisely are core our platform.

As a web developer assisting a charity with a fundraising campaign, you can customise the page layout in our WYSIWYG page builder, edit the full site styles as SASS/SCSS, and build your own React components to add to the page as custom blocks.

In this quickstart, we're going to go through how to set up a development environment and deployment flow for your Raisely campaign.

What you can customise

There are three main ways a developer can add functionality to a Raisely campaign:

• By editing the CSS
• By building custom React components
• By integrating with Raisely's API

In this guide, we're focussing on the first two – editing your campaign styles, and building new components.

CSS

All Raisely campaigns have a core stylesheet that can be edited by developers. This stylesheet is written in SASS so that you can access variables and style settings defined in your campaign's Design tab. We expose a wide range of variables and mixins to make styling easier, you can see our full styling docs here.

📘

Organise your CSS

No-one likes a CSS file that's a 1000 lines long. Raisely lets you organise your CSS into folders. You can create new folders and files in your CLI-supported project. Raisely will automatically concatenate them when compiling them, in alphabetical order.

Custom Components

Custom components are small, single-file React components that can be added to a Raisely page via our page editor. Custom components are a great way to add functionality to your Raisely campaign, inject custom DOM, call APIs, or build new user experiences.

A custom component has:

• A JavaScript file with a React component
• A config file, with a field definition

When you create a custom component, it is made available via Raisely's block picker. You can create a range of input fields for a non-technical user to enter content, which can be received into your component as variables.

The Raisely CLI

The Raisely CLI is a simple command-line interface to work locally on Raisely campaigns. It means you can code in your favourite code editor, use version control, and other local development resources.

Setting up a project

To install the CLI you first need Node.js (at least version 13) on your computer.

Once Node.js is installed, you can install the CLI by

1. Run npm install @raisely/cli -g
2. Go into your project folder and run: raisely init

You will be prompted for your Raisely login details and the campaigns you'd like to sync. Your project will then be set up with two folders, components for all your custom components, and stylesheets with subfolders for each campaign.

Common Functions

Create a new component
To create a new custom component, run: raisely create. You'll be prompted for your component name, and then it'll be downloaded ready for you to edit.

Deploy your changes
To upload your local folder to Raisely, run: raisely deploy. You'll replace all styles and components in your Raisely campaign with your local copies.

Solo development

If you're working solo on a project, and don't need version control, then you can use the CLI to work directly in Raisely.

1. In a terminal, run raisely start

The CLI will watch for any change to your stylesheets or components and upload them instantly to Raisely. You'll see these changes reflected on your Raisely campaigns almost instantly.

Team development

If you're working in a team, you likely need (and are familiar with) version control like Git. You can't use raisely start in a team, as you'll constantly write over each others changes.

Instead, you can use raisely local to work on your campaign locally, with locally compiled components and stylesheets.

Then, commit your changes and use your CI/CD workflow to deploy them to your campaign.

Local Development Workflow

Here's how you can set up a local development workflow on Raisely, for your team. For this guide we're assuming you have the CLI installed, and have a basic understanding of Git.

Setting up

1. Create a blank project folder
2. Run raisely init and follow the prompts to set up your project
3. Add a .gitignore file with the following contents:

// the raisely config file - don't commit this, it contains credentials
.raisely.json

// standard ignores
.DS_Store
.env
node_modules

4. Create a new git repo: git init
5. Complete your first commit: git add . && git -am "Initial Commit"
6. Push your commit to your version management tool: git remote add origin [url] then git push -u origin main

Starting work

With your project initialised, you're ready to start making changes. Run raisely local and select the campaign you're working on.

The CLI will boot up a local server, and open your campaign in your browser. The URL will be http://localhost:8015/.

Now, you can edit any stylesheets or components. Your campaign will automatically reload and reflect these changes, however they will not be visible on the live Raisely website.

Saving your changes

Once you're done working, you can commit your changes and deploy them to Raisely. This publishes them, making them available on the public Raisely website.

Run: raisely deploy.

Automatic deploys with CI/CD or GitHub Actions

You can use the Raisely CI in CI/CD workflows to automatically deploy your Raisely project to the right campaign. This can be used to deploy your develop branch to a staging campaign, and your main branch to production.

To do this, the Raisely CLI supports environment variables and you can run a campaign in your workflow like:

RAISELY_CAMPAIGNS={{campaign uuid}} RAISELY_TOKEN={{api key}} raisely deploy

If you use GitHub, you can do this automatically using GitHub Actions and the raisely/deploy action.

1. Create a .github/workflows/raisely-deploy.yml file in your GitHub repo.
2. Add the following code to the raisely-deploy.yml file

on: push
name: Raisely Deploy Demo
jobs:
  raiselyDeploy:
    name: Raisely Deploy
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Raisely Deploy
      uses: raisely/deploy@v1
      with:
        campaign: ${{ secrets.RAISELY_CAMPAIGN }}
        apikey: ${{ secrets.RAISELY_API_KEY }}

3. In your GitHub repository, go to Settings > Sections > Actions. Add a secret called RAISELY_CAMPAIGN with your campaign UUID, and RAISELY_API_KEY with your campaign's API key. You can find both of these in your Raisely admin panel, under Settings > API & Webhooks.
4. Commit your changes, and confirm the task succeeded under Actions in your repository.

📘

Require local development

If you're managing your Raisely campaign styles and components through a git repository, you likely don't want anyone making changes outside of that repository otherwise you risk those changes being overwritten when you deploy your code.

You can require local development under Organisation > Developers. This will prevent any code changes except through raisely deploy.

Wrapping up

In this guide we've covered:

1. What you can change in a Raisely campaign
2. How to install and use our CLI
3. How to set up a git workflow with CI/CD for your Raisely campaign

When you're working in Raisely, it's good to be aware of our style variables and built-in components. You can use these to save you time, and make sure your code works with the editor inside Raisely.

If you have any questions, just email [email protected] and our support engineers will be able to help you out.