-
Notifications
You must be signed in to change notification settings - Fork 206
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
The current README dates back to when `create-daml-app` was its own repo, and seems mostly written from the perspective of being the default home page for the project. These days, `create-daml-app` serves two purposes: 1. As the core starting point for the Getting Started Guide, we can assume people who are totally new to Daml will be following the getting started guide. How else would they even know about this template? In that case, I think it's fair to assume the user will *not* be looking to the README for guidance. Therefore, repeating the documentation here seems a bit pointless. 2. As a template to quickstart the creation of a "custom" app that is not the GSG. For that use-case, the README is the place where people would look for information, but at that point the information they're looking for are more along the lines of quick refreshers of what commands to run than explanations on how to use the app as Alice and Bob. CHANGELOG_BEGIN CHANGELOG_END
- Loading branch information
1 parent
8501832
commit c155935
Showing
1 changed file
with
45 additions
and
92 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,121 +1,74 @@ | ||
| [](https://www.daml.com) | ||
|
|
||
| [](https://docs.daml.com/getting-started/installation.html) | ||
| [](https://github.com/digital-asset/daml/blob/main/LICENSE) | ||
|
|
||
| # Welcome to _Create Daml App_ | ||
| # __PROJECT_NAME__ | ||
|
|
||
| This repository contains a template to get started with developing full-stack | ||
| [Daml](https://daml.com/) applications. The demo application covers the following aspects: | ||
| See [documentation] for details. | ||
|
|
||
| 1. A [Daml](https://docs.daml.com/index.html) model of a simple social network | ||
| 2. A UI written in [TypeScript](https://www.typescriptlang.org/) and [React](https://reactjs.org/) | ||
| [documentation]: https://docs.daml.com/getting-started/installation.html | ||
|
|
||
| The UI is developed using [React](https://reactjs.org/), | ||
| [Semantic UI](https://react.semantic-ui.com/) and its | ||
| official [React integration](https://react.semantic-ui.com/). | ||
| The whole project was bootstrapped with | ||
| [Create React App](https://github.com/facebook/create-react-app). | ||
| Regardless of these choices, all Daml specific aspects of the UI client are | ||
| written in plain TypeScript and the UI framework should hence be easily | ||
| replaceable. | ||
| Please ask for help on [the Daml forum] if you encounter any issue! | ||
|
|
||
| [the Daml forum]: https://discuss.daml.com | ||
|
|
||
| ## Getting started | ||
| ## Development Quick Start | ||
|
|
||
| Before you can run the application, you need to install the | ||
| [Node](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) package manager for JavaScript. | ||
| You need to have [Node.js] and [Daml] installed. | ||
|
|
||
| There are two steps to build the project. | ||
| First, we need to generate TypeScript code bindings for the compiled Daml model. | ||
| At the root of the repository, run | ||
| ``` | ||
| daml build | ||
| daml codegen js .daml/dist/__PROJECT_NAME__-0.1.0.dar -o ui/daml.js | ||
| ``` | ||
| The latter command generates TypeScript packages in the `daml.js` directory. | ||
| [Node.js]: https://nodejs.dev | ||
| [Daml]: https://docs.daml.com | ||
|
|
||
| Next, navigate to the `ui` directory and install the dependencies and build the app by running | ||
| ``` | ||
| cd ui | ||
| npm install | ||
| npm run-script build | ||
| ``` | ||
| The last step is not absolutely necessary but useful to check that the app compiles. | ||
| First, start the Daml components: | ||
|
|
||
| To start the application, there are again two steps. | ||
| In one terminal in the root directory, start a Daml ledger using | ||
| ``` | ||
| ```bash | ||
| daml start | ||
| ``` | ||
| This must continue running to serve ledger requests. | ||
|
|
||
| Then in a second terminal window in the `ui` directory, start the UI server via | ||
| ``` | ||
| npm start | ||
| ``` | ||
| This should open a browser window with a login screen. | ||
| If it doesn't, you can manually point your browser to http://localhost:3000. | ||
| This will: | ||
|
|
||
| - Build you Daml code once. | ||
| - Generate JavaScript code (and TypeScript definitions) for your Daml types. | ||
| - Start a Daml sandbox gRPC server (on 6865). | ||
| - Start a Daml HTTP JSON API server (on 7575). | ||
| - Watch for the `r` key press (`r` + Enter on Windows); when pressed, rebuild | ||
| all of the Daml code, push the new DAR to the ledger, and rerun the JS/TS | ||
| code generation. | ||
|
|
||
| ## A quick tour | ||
| Next, start the JS dev server: | ||
|
|
||
| You can log into the app by providing a user name, say `Alice`. For simplicity | ||
| of this app, there is no password or sign-up required. You will be greeted by | ||
| a screen indicating that you're not following anyone and that you don't have | ||
| any followers yet. You can change this by following someone in the upper box, | ||
| say `Bob`. After that, let's log out in the top right corner and log in as `Bob`. | ||
| ```bash | ||
| cd ui | ||
| npm install | ||
| npm start | ||
| ``` | ||
|
|
||
| As `Bob`, we can see that we are not following anyone and that `Alice` is follwing | ||
| us. We can follow `Alice` by clicking the plus symbol to the right of here name. | ||
| This starts a server on `http://localhost:3000` which: | ||
|
|
||
| - Builds all of your TypeScript (or JavaScript) code (including type | ||
| definitions from the codegen). | ||
| - Serves the result on :3000, redirecting `/v1` to the JSON API server (on | ||
| `localhost:7575`) so API calls are on the same origin as far as your browser | ||
| is concerned. | ||
| - Watch for changes in TS/JS code (including codegen), and immediately rebuild. | ||
|
|
||
| ## Deploying to Daml Hub | ||
|
|
||
| Deploying `__PROJECT_NAME__` to the hosted Daml platform | ||
| [Daml Hub](https://hub.daml.com/) is quite simple. Log into your Daml Hub | ||
| account, create a new ledger and upload your Daml models and your UI. | ||
|
|
||
| To upload the Daml models, compile them into a DAR by executing | ||
| ``` | ||
| daml build -o __PROJECT_NAME__.dar | ||
| ``` | ||
| at the root of your repository. Afterwards, open to the Daml Hub website, select | ||
| the ledger you want to deploy to, go to the "Daml" selection and upload the | ||
| DAR `__PROJECT_NAME__.dar` you have just created. | ||
| To build everything from scratch: | ||
|
|
||
| To upload the UI, create a ZIP file containing all your UI assets by executing | ||
| ``` | ||
| ```bash | ||
| daml build | ||
| daml codegen js .daml/dist/__PROJECT_NAME__-0.1.0.dar -o ui/daml.js | ||
| (cd ui && npm install && npm run-script build && zip -r ../__PROJECT_NAME__-ui.zip build) | ||
| cd ui | ||
| npm install | ||
| npm run-script build | ||
| zip -r ../__PROJECT_NAME__-ui.zip build | ||
| ``` | ||
| at the root of the repository. Afterwards, select the "UI Assets" tab of your | ||
| chosen ledger on the Daml Hub website, upload the ZIP file | ||
| (`__PROJECT_NAME__-ui.zip`) you have just created and publish it. | ||
|
|
||
| To see your deployed instance of `__PROJECT_NAME__` in action, follow the | ||
| "Visit site" link at the top right corner of your "UI Assets" page. | ||
|
|
||
|
|
||
| ## Next steps | ||
|
|
||
| There are many directions in which this application can be extended. | ||
| Regardless of which direction you pick, the following files will be the most | ||
| interesting ones to familiarize yourself with: | ||
|
|
||
| - [`daml/User.daml`](daml/User.daml): the Daml model of the social network | ||
| - `daml.js/__PROJECT_NAME__-0.1.0/src/User.ts` (once you've generated it): | ||
| a reflection of the types contained in the Daml model in TypeScript | ||
| - [`ui/src/components/MainView.tsx`](ui/src/components/MainView.tsx): | ||
| a React component using the HTTP Ledger API and rendering the main features | ||
|
|
||
|
|
||
| ## Useful resources | ||
|
|
||
| TBD | ||
|
|
||
| Next you need to create a ledger on [Daml Hub], upload the files | ||
| `.daml/dist/__PROJECT_NAME__-0.1.0.dar` (created by the `daml build` command) | ||
| and `__PROJECT_NAME__-ui.zip` (created by the `zip` command based on the result | ||
| of `npm run-script build`). | ||
|
|
||
| ## How to get help | ||
| [Daml Hub]: https://hub.daml.com | ||
|
|
||
| TBD | ||
| Once both files are uploaded, you need to tell Daml Hub to deploy them. A few | ||
| seconds later, your website should be up and running. |