The ODD App Template is a clone-and-go template for building a web application using the ODD SDK, fast. Clone, customize, and deploy to have a running distributed app in mere minutes.
The ODD SDK is alpha software.
We recommend you do not develop production applications using the ODD App Template at this time. We're working on making it reliable, fast, and awesome, but we're not there yet!
The ODD SDK empowers developers to build fully distributed web applications without needing a complex back-end. The SDK provides:
ODD applications work offline and store data encrypted for the user by leveraging the power of the web platform. You can read more about the ODD SDK in Fission's ODD SDK Guide.
The ODD App Template provides a silky-smooth user experience out of the box. Creating an account and linking a second device feels familiar, comfortable, and obvious. ODD SDK authentication is key-based rather than password-based, so we've focused heavily on the authentication flows, borrowing language and screens from two-factor auth flows.
The app template is built with modern web technologies:
The app template includes a functioning application: an image gallery. Check out the image gallery code to learn how an ODD application handles things like file uploads, directories, etc.
You can try out the template yourself here.
Ready? Let's go.
Prerequiste: ensure you are running Node 16.14 or greater, but not Node 17 (18 is fine though!).
Clone the repository:
git clone git@github.com:oddsdk/odd-app-template-react.git
Install the dependencies.
npm install
Start the local development server.
npm run dev
Navigate to http://localhost:5173
in your web browser.
The app template is designed to be easy for you to make it your own. Here's how:
Rename your application.
In /src/lib/app-info.ts
:
appName
to the name of your app.appDescription
to a simple, 1-sentence description of your app.oddNamespace
with your project details.appURL
to the production URL.In package.json
, change name
to your application's name.
Customize your app's logo.
/src/components/icons/Brand.svelte
. Target an image that is 35 pixels high./static
by following the instructions in this blog post/src/lib/app-info.ts
, change appImageURL
to match the URL of your embed image./src/routes/+layout.svelte
, update og:image:width
and og:image:height
to the size of your embed image.Customize the look and feel.
The app template is built using Tailwind and DaisyUI. You can customize basic theme colors by editing /tailwind.config.css
. Check out the DaisyUI Theme Generator to play around with theme colors or read the customization guide to customize the component appearance.
Clear out the app's home page.
The home page content is in /src/routes/+page.svelte
. Delete everything in the file (but don't delete the file!) to start over with a blank home page.
Remove the image gallery demo app code.
If you're not building an image gallery, you don't need the gallery demo code, except perhaps to learn from. To get rid of it, delete:
/src/routes/gallery
initializeFilesystem
function in /src/lib/auth/account.ts
creates directories used by WNFS. Change those to what you need for your app or delete them if you're not using WNFS.π You're ready to start adding custom functionality! π
Check out the ODD SDK Guide for ODD SDK questions or UCAN.xyz for UCAN questions.
When you go through the registration flow in WAT, the username you type in the form field has a #{DID}
appended to it in the background. We did this to enable discord style usernames where users can share the same usernames, but have unique identifiers attached to the end to distinguish them from one another. We then create a hash of the fullUsername
(the one with the #{DID}
appended to the end) that is passed to the ODD SDK. So the ODD SDK only has a notion of the hashed
username currently. This should also allow users to create usernames using emojis or non-English characters. Also, this is the only username schema that currently supports our File System recovery flow.
You donβt necessarily need to follow that same pattern though. If you were to register two of the same usernames in the app without hashing them, you would be able to call session.authStrategy.isUsernameAvailable(username)
to ensure duplicate usernames aren't present in the app. We will be working on porting some of this functionality over to the ts-ODD
library over the next while and we will be updating the docs to reflect that.
Please take a look at our init function to see how we are currently constructing the username schema.
Any static hosting platform should be supported. The ODD App Template is currently deployed on:
Try out ODD App Template on Fission
An ODD application can be published to IPFS with the Fission CLI or the Fission GitHub publish action.
To publish with the Fission CLI:
fission setup
to make a Fission accountnpm run build
to build the appfission.yaml
fission app register
to register a new Fission app (accept the ./build
directory suggestion for your build directory)fission app publish
to publish your app to the webYour app will be available online at the domain assigned by the register command.
To set up the GitHub publish action:
base64 ~/.config/fission/key/machine_id.ed25519
FISSION_MACHINE_KEY
publish.yml
with the name of your registered appSee the Fission Guide and the publish action README for more details.
In order to deploy your ODD application on Netlify:
Try out the ODD App Template on Vercel.
In order to deploy your ODD application on Vercel:
build
.Try out the ODD App Template on Cloudflare Pages.
In order to deploy your ODD application on Cloudflare Pages:
SvelteKit
from the "Framework preset".build
.NODE_VERSION
and value of 16
.Export a static build.
npm run build
The build outputs the static site to the build
directory.