9bb98ce6d3
* Add intro * Add getting started with idea of `create-portal-app` * Major refactor moving developer stuff into developer section.
🌀 Portal is a framework for rapidly building rich data portal frontends using a modern frontend approach (javascript, React, SSR).
Portal assumes a "decoupled" approach where the frontend is a separate service from the backend and interacts with backend(s) via an API. It can be used with any backend and has out of the box support for CKAN. portal is built in Javascript and React on top of the popular Next.js framework.
Getting Started
Setup
Install a recent version of Node. You'll need Node 10.13 or later.
Create a Portal app
To create a Portal app, open your terminal, cd into the directory you'd like to create the app in, and run the following command:
npm init portal-app my-data-portal
NB: Under the hood, this uses the tool called create-next-app, which bootstraps a Next.js app for you. It uses this template through the --example flag.
If it doesn’t work, please open an issue.
Guide
Styling 🎨
We use Tailwind as a CSS framework. Take a look at /styles/index.css to see what we're importing from Tailwind bundle. You can also configure Tailwind using tailwind.config.js file.
Have a look at Next.js support of CSS and ways of writing CSS:
https://nextjs.org/docs/basic-features/built-in-css-support
Backend
So far the app is running with mocked data behind. You can connect CMS and DMS backends easily via environment variables:
$ export DMS=http://ckan:5000
$ export CMS=http://myblog.wordpress.com
Routes
These are the default routes set up in the "starter" app.
- Home
/ - Search
/search - Dataset
/@org/dataset - Resource
/@org/dataset/r/resource - Organization
/@org - Collection (aka group in CKAN) (?) - suggest to merge into org
- Static pages, eg,
/aboutetc. from CMS or can do it without external CMS, e.g., in Next.js
New Routes
TODO
Developers
Boot the local instance
Install the dependencies:
yarn # or npm i
Boot the demo portal:
$ yarn dev # or npm run dev
Open http://localhost:3000 to see the home page 🎉
You can start editing the page by modifying /pages/index.tsx. The page auto-updates as you edit the file.
Tests
We use Jest for running tests:
yarn test # or npm run test
# turn on watching
yarn test --watch