Monorepo for Archive.org UX development and prototyping.
Note: This is work-in-progress code, and until development has stabilized, things may change a lot. This library is being published with our use cases in mind and is not necessarily meant to be consumed by the broader public.
There are multiple npm packages in this repo, and Lerna is used to manage them.
Install dependencies on all packages.
yarn install
yarn run lerna bootstrap
yarn run lerna link
Run our local UI component development environment.
cd packages/ia-components && yarn run storybook
There are several node packages in this one repo. They are located under the packages directory.
At the time of writing, there are 4 packages:
The ia-components package contains reusable "components" (loosely). It is actually just a package that is included into Archive.org's codebase. Having an external package makes it easier for new developers to contribute development.
It's easy to test these components using the "prototypes" package. The final integration into the Archive.org website still needs to be done by internal staff.
As a convention, the preferred framework is React, but vanilla JS components are also possible.
Within ia-components there are two subdirectories: sandbox and live. The idea is that code in the live directory is used in production. But in sandbox, components might still be works-in-progress, new designs, etc, and only used in prototypes.
This is still a TODO, but the idea is that common CSS and a design style guide could live here.
The ia-js-client package is a hybrid JavaScript and NodeJS client to the Internet Archive's APIs. It is written in TypeScript. It is used in both the ia-components and ia-prototype-apps packages for fetching data. See packages/ia-js-client/README.md for more info.
Prototypes are basically little websites built using code from ia-components. They can serve many purposes. For example, a prototype can be used to test the integration of several components in ia-components. A prototype can also be made by the UX team to test a new design using live data.
Of course, a prototype could also be made outside of this repo, and that will make sense in some cases.
Since the prototypes package is a "packages/ia-prototype-apps" and there are a lot of other files at that level, there is a second directory "packages/ia-prototype-apps/apps" and this is where the actual content lives.
See packages/ia-prototype-apps/README.md for more info.
Prototypes can be run like this:
cd packages/ia-prototype-apps
yarn run parcel apps/examples/example-hello/index.html
After, you can try running a more complex example:
yarn run parcel apps/details-react/index.html
As stated earlier, there are multiple npm packages in this repo, and Lerna is used to manage them. The command used to publish changes is the following:
yarn run lerna publish --skip-git --canary
This will provide a step-by-step prompt, where you can decide whether this is a major, minor, or patch release. It's okay to try it, and then use control+c, to exit without having changes. However, once you publish a release, it's irrevocable.
This is structured so that there is compatibility with the upstream Archive.org codebase.
- Use
lessinstead ofscss - Do not import other asset types into js code. E.g. do NOT do
import 'styles.less'. Instead, create a separatelessfile, e.g.styles.lessalongside the JavaScript code, and this will be imported into the petabox'sarchive.lessat integration time.
Currently, we are using Airbnb's styleguide and will extend accordingly. We have added ESLint to help with staying in convention.
We use StorybookJS to show usage examples of our components. For details on how to run StorybookJS, visit the ia-components readme: IA Components Readme
Run Storybook:
cd packages/ia-components && yarn run storybook
JestJS is pliable enough for us to test in JavaScript and TypeScript. Try running our tests:
cd packages/ia-components && yarn run test
We are using the common debug module.
To add to a module, add a line like
const debug = require('debug')('ia-components:COMPONENTNAME')
To enable, for example, debugging in all ia-components, and debugging in the dweb-archive:Nav module.
In Node add a line to your top level application BEFORE requiring or importing the other modules.
process.env.DEBUG="ia-components:* dweb-archive:Nav"
In Browser, add a line to your index.html or equivalent BEFORE including the bundle.
<script type="text/javascript">localStorage.debug = "dweb-archive dweb-archive:* dweb-transports dweb-transports:* dweb-objects dweb-objects:*";</script>
in v2mocks there is code that is pulled from IA "View Source" and converted to JSX using this tool:
https://magic.reactjs.net/htmltojsx.htm
Archive.org v2 uses Bootstrap 3.0. Docs can be found here: http://bootstrapdocs.com/v3.0.0/docs/css/#overview