-
Notifications
You must be signed in to change notification settings - Fork 6
Draft Quickstart
Note, wiki articles are non authoritative, draft content. See the wiki Home page for more details.
This quickstart is a forward-looking design document that informs our next steps of development, and should not be used to build Cards yet. It does not work as-written currently. After there is a release of the CLI and the quickstart is published to docs.cardstack.com, that is the point where developers should give it a try, so stay tuned on Discord and Twitter for announcements. Technical progress is tracked in Issues, if you would like to follow along with which part we're working on next!
The goal of this quickstart is to keep it as short and sweet as possible. The target audience is developers who are comfortable with command line tools. More documentation work is underway with detailed information, in a resources that we refer to as the Cardstack Guides. The Guides will have resources for both technical and non-technical audiences.
Welcome to Cardstack! Follow these step-by-step instructions to make your own full-stack project using the Card SDK. The result will be an application that has lazy loading, code splitting, intelligent data caching, and some UI components to get you started.
First, you need the following installed on your Mac, Linux, or Windows computer:
- git
- npm and Node.js
- yarn
- Docker - a free container manager
- Ember CLI
- Linux and Mac systems should also install Watchman
- If you are developing in a Windows environment, use Bash if you would like to be able to follow this tutorial exactly as written.
- It is optional, but recommended, to install the Ember Inspector for debugging your front end work.
Developers should be familiar with JavaScript, HTML, and git in order to follow along with these Guides.
Then, install the Cardstack CLI:
Future:
npm install -g @cardstack/cliCurrent:
git clone https://github.com/cardstack/cardstack.git
cd cardstack
yarn install
alias cardstack='node ~/<path to cardstack repo>/cardstack/packages/cli/bin/cardstack.js'cardstack start
This will ensure that the supporting Docker services are running and then start the Cardstack Hub (the standardized backend/server that supports all cards). You only need to run this one time to support all local card development, no matter how many card projects you are working on.
The Cardstack CLI creates the files you will need:
Future:
cardstack new my-card-name
cd my-card-name
cardstack play .
> Your card is loaded into the Hub, preview it at
> http://localhost:4200/?isolate=your-card/newNow you can follow the link and see the welcome message:
Your card contains files like:
components/isolated.hbscomponents/isolated.jscomponents/isolated.csscomponents/embedded.hbscomponents/embedded.jscomponents/embedded.css
All cards present in two different formats: isolated and embedded. The isolated format is the "full screen" format, the embedded format is small and intended to appear inside other cards.
Current:
cardstack new my-card-name
This will generate the files. cardstack play is a work in progress. Everything after this point describes the work plan.
We'll start by working on the isolated template.
Open the file at components/isolated.hbs and change the markup:
<h1>My first card</h1>
<p>Some text</p>In your Card template, you can write regular HTML or Ember Handlebars.
As you make changes, your page at http://localhost:4200 will reload. (It's not necessary to keep running cardstack play.)
- tell the user how to edit the schema.js file directly
- have them put the
{{card.title}}reference into the template - now you see a editable field in the right edge
- if you fill it out, the right edge now shows an unsaved state
- when you save, we visually show that your new card instance goes somewhere. Probably into the bottom edge, because that's always available as a generic card browser.
- you can swap between instances using the bottom edge
- you can hit "New" and start with a blank instance.
- you can delete instances
- your instances are actually saved in ~/.cardstack/your-stuff-repo
(getting to here first seems good)
- add the template reference to the content first:
{{card.title}} - shows a message in the right edge about unknown field title, with a button to create it
- when you create it you get to pick its field-type
- when you create it, we are writing out an updated schema.js file for you in the definition.
- now you see a editable field in the right edge
- if you fill it out, the right edge now shows an unsaved state
- when you save, we visually show that your new card instance goes somewhere. Probably into the bottom edge, because that's always available as a generic card browser.
- use card embedding to synthesize a dashboard combining some of your own info and some of the third-party sourced info
There's no separate "project" to work in, if you make a separate card, all your existing stuff is still visible and integrated.
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.
Get your card into the catalog that we searched earlier, so other people can build off it.
Publish to NPM? Register with The Card Catalog?
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!
- adopting a card via UI? a bottom-edge card browser