Skip to content

Draft Quickstart

Jump to bottom
Jen Weber edited this page May 17, 2019 · 18 revisions

Note, wiki articles are non authoritative, draft content. See the wiki Home page for more details.

This Quickstart doesn't work yet. It is an example of the type of experience we could aim to deliver for new developers. When we are closer to having the CLI ready, this can go into a PR.

Quickstart

Welcome to Cardstack! Follow these step-by-step instructions to make your own full-stack project using the Card SDK.

Installation

To get started, you will need the following installed on your computer:

Then, install the Cardstack CLI:

npm install -g @cardstack/cli

If you're new to developing in JavaScript, watch this video to see someone setting up their Cardstack developer environment.

Start the Hub

The Hub is the environment where your Card will run.

cardstack run

Now you can visit http://localhost:4200 and see the welcome message:

IMAGE

Add some static content to a Card

The welcome message you saw is displayed on a Card. Open the file at path/to/file and change the markup:

some markup

Your page at http://localhost:4200 will reload. In your Card template, you can write regular HTML or Ember Handlebars.

Choose a data source

Next, we'll add some data persistence. In this tutorial, we'll create a form input whose results will be saved into the postgres database.

Run the following command to generate a Card Schema that uses the postgres plugin:

cardstack generate schema --postgres

You'll see a new Card Schema file, filename.js, which has some boilerplate in it to get you started:

// show boilerplate configured to postgres

Add a formEntry, where we will store user inputs:

// show adding schema

Save some data using a Card

Now, let's set up an input in the card and a submit button. First, we will create our form.

<label for="my-input">
    What is one of your favorite locations for photography?
</label>

<input type="text" id="my-input" value={{this.userEntry}}>

<button>
    Submit
</button>

Next, we tell the button what to do when clicked. In your path/to/card.js file, let's write a function that we can attach to the button.

@action
submitLocation() {
  // save this.userEntry to postgres
}

Now, let's add this form action to the button we made in path/to/card.hbs:

<button onclick={{action 'submitLocation'}}>
    Submit
</button>

Visit http://localhost:4200 in your browser. When you click the button, an API request will save the entry to the database!

Display Card Data

Once you have made some entries, it's time to display them in the app. Add the following to your path/to/card.hbs, below the button:

<h1>Previous entries</h1>
<ul>
  {{#each content.formEntries as |entry|}}
     <li>
        {{entry}}
     </li> 
  {{/each}}
</ul>

Visit http://localhost:4200 to see your list of favorite locations.

Deploy your project

Cardstack projects can be deployed to any major cloud provider. In this tutorial, we'll show you how to deploy to Azure or Heroku. Since we didn't add authentication into this app yet, keep in mind that anyone can submit things through your form. To learn about authentication, see the "Learn more" section below.

Azure

Azure is a hosting service with broad international support.

If you don't have Azure already, set up an account following these instructions.

Then, to deploy your Card to Heroku, use the following command:

cardstack deploy --to azure

Heroku

Heroku requires minimal configuration and it has a generous free tier that does not require a credit card to use.

If you don't have Heroku already, set up an account following these instructions.

Then, to deploy your Card to Heroku, use the following command:

cardstack deploy --to heroku

When it's finished, your app's URL will be shown. Visit it to see your app live!

Learn more

This is just the beginning of what the Card SDK can do. Follow the Cardstack Tutorial and Guides to add features like authentication, routing, integrating with other data sources, caching, and more!

Clone this wiki locally