Unlocking Easy File Management in Arweave: Your Ultimate Guide to Web3 Frontend Path Manifests with 4EVERLAND
Hey there, Web3 enthusiast! Are you struggling with managing paths and transaction IDs in Arweave? You’re in luck! In this tutorial, we’ll demystify the concept of “Path Manifests” — a brilliant feature that lets you handle user-defined subpaths mapped with Arweave transaction IDs. Think of it as a way to create a neat directory structure, helping you manage files and assets of your web application effortlessly.
Why Do You Even Need Path Manifests?
When you upload data to Arweave, it’s enveloped in a transaction. This transaction has a URL identifier that’s basically a SHA-256 hash of the transaction signature. So, it’s not exactly human-friendly, nor is it something you can customize.
Here’s a simple example to break it down:
Say you have a small web application with the following structure:
index.html
about.html
js/app.js
css/style.css
assets/fonts/font.woff
assets/fonts/font.ttf
assets/img/logo.png
assets/img/icon.png
Once uploaded to Arweave, let’s say your css/style.css gets an ID like XEfZIr3DOFXiKZ2I3XujAsPpvryTts2dVyr6dqrrmUm. To access it, you would use a URL like https://arweave.net/XEfZIr3DOFXiKZ2I3XujAsPpvryTts2dVyr6dqrrmUm.
But hold on! Now you’ve got a problem. Your index.html probably references this CSS file like so:
<link href="css/style.css" rel="stylesheet" />
This won’t work anymore! You’d have to update it to:
<link href="XEfZIr3DOFXiKZ2I3XujAsPpvryTts2dVyr6dqrrmUm" rel="stylesheet" />
Or even inline it:
<style type="text/css">
/* Contents of css.style.css */
</style>
This process becomes increasingly difficult when your JavaScript code dynamically references files. Also, this approach doesn’t provide you and your users with human-readable paths or URLs.
The Circular Dependency Conundrum
Wait, there’s more! You could run into the dreaded circular dependency. If index.html and about.html reference each other, updating one with the new Arweave transaction ID means you have to re-sign and update the other, resulting in a never-ending loop of dependencies.
That’s where Path Manifests come to your rescue.
How to Craft Your Path Manifests: The Nitty-Gritty Details
Alright, you’ve gotten the hang of why Path Manifests are a lifesaver in Web3 frontend development. Now, let’s roll up our sleeves and dive into how to actually create one.
Understanding the Path Manifest Schema
Path Manifests are JSON objects and come with several key-value pairs. Each of these keys serves a specific purpose. Let’s deconstruct it:
Mandatory Fields
manifest: Type is string. This identifies that what you're creating is a path manifest for Arweave. It must be set to arweave/paths.
version: Type is string. This tells us which version of the manifest specification you're using. As of now, it's 0.1.0. For future updates, just keep an eye on semver.
paths: Type is object. This is where the magic happens. It maps your subpaths to Arweave transaction IDs. Each subpath key has an associated id which is the transaction ID for that particular file or asset.
Optional Fields
index: Type is object. This specifies what should happen when someone tries to access the manifest directly. If you set it, it must contain a behavior to adopt, which currently is path.
index.path: Type is string. If set, this is the default path that will load when the manifest is accessed. It must reference a key in the paths object, not a transaction ID.
Pro-Tips
Your path manifest transaction must only contain this JSON object.
The Content-Type tag must be set to application/x.arweave-manifest+json.
Example Time!
Here’s a sample manifest JSON code snippet to illustrate how it all comes together:
{
"manifest": "arweave/paths",
"version": "0.1.0",
"index": {
"path": "index.html"
},
"paths": {
"index.html": {
"id": "cG7Hdi_iTQPoEYgQJFqJ8NMpN4KoZ-vH_j7pG4iP7NI"
},
"js/app.js": {
"id": "fZ4d7bkCAUiXSfo3zFsPiQvpLVKVtXUKB6kiLNt2XVQ"
},
"css/style.css": {
"id": "fZ4d7bkCAUiXSfo3zFsPiQvpLVKVtXUKB6kiLNt2XVQ"
},
"css/mobile.css": {
"id": "fZ4d7bkCAUiXSfo3zFsPiQvpLVKVtXUKB6kiLNt2XVQ"
},
"assets/img/logo.png": {
"id": "QYWh-QsozsYu2wor0ZygI5Zoa_fRYFc8_X1RkYmw_fU"
},
"assets/img/icon.png": {
"id": "0543SMRGYuGKTaqLzmpOyK4AxAB96Fra2guHzYxjRGo"
}
}
}
In this example, if someone accesses the manifest directly, it will load index.html by default. All the subpaths and their corresponding transaction IDs are clearly outlined in the paths object.
And there you have it! You’ve now become proficient in crafting and understanding Path Manifests. In the next part of this tutorial, we will look at how to actually implement these Path Manifests into your Web3 projects. So, don’t go too far!
Understanding URL Resolution in Arweave Gateways
Applicability Scope
Note that the rules for URL resolution are specific to the /[:txid] endpoint in Arweave gateways. These rules don't apply to /tx/[:txid] endpoints.
URL Anatomy and Resolution
When a user requests a URL from an Arweave gateway, the gateway must first identify the manifest transaction ID (manifestId) and the specified subpath. A typical Arweave URL might look like this:
Full URL: https://arweave.net/dtOrr7JHEI6MTy9fqUJ48inydg4EiunfSzWRmCJ0KgS/css/style.css
Protocol: https
Host: arweave.net
Manifest ID: dtOrr7JHEI6MTy9fqUJ48inydg4EiunfSzWRmCJ0KgS
Subpath: css/style.css
Gateway Resolution Steps
Content-Type Verification: The gateway must first check the Content-Type of the page being requested. If the Content-Type is application/x.arweave-manifest+json, then further processing is needed; otherwise, the data is served as-is.
Manifest Parsing and Validation: Next, the gateway parses the manifest transaction’s data and should verify its contents according to the schema described in the document.
Subpath Matching: The gateway searches the manifest for a key that corresponds to the requested subpath. If a match is found, the gateway responds with the transaction ID content specified in manifest.paths[subpath].id.
HTTP Codes and Redirects: A HTTP 200 status code should be returned if content is found. Redirects are not allowed; the user's URL must remain unchanged in the browser.
Error Handling: If the manifest points to an invalid transaction ID or one that can’t be accessed, a HTTP 404 status should be returned.
Index Mapping: If a manifest is accessed directly (no subpath specified), and it has an index.path value, that value should be mapped to the manifest paths and resolved accordingly. Redirects to index.path are not allowed.
Listing Available Paths: If no index.path is defined, the gateway should display a list of all valid paths in a user-friendly HTML format.
ETag for Caching: ETag headers are important for caching. The ETag should be set to the transaction ID of the actual content, not the manifest, unless the manifest is being accessed without a subpath and no index is defined.
Examples
Here are some example scenarios based on hypothetical manifest files:
No subpath specified: The gateway will resolve to the data in cG7Hdi_iTQPoEYgQJFqJ8NMpN4KoZ-vH_j7pG4iP7NI as index.html is defined as index.path.
Valid subpath specified: A request for /mmJhKOPp2o73LXze05mj5qPVlgu4MsDzqCwpWKqoc7U/assets/img/logo.png would return the content at QYWh-QsozsYu2wor0ZygI5Zoa_fRYFc8_X1RkYmw_fU.
Invalid subpath: A request for a non-existing path like /mmJhKOPp2o73LXze05mj5qPVlgu4MsDzqCwpWKqoc7U/path/does/not/exist.txt will return a HTTP 404.
No default index defined: If no index.path is present, the gateway will display an HTML page listing all valid paths available in the manifest.
By understanding these resolution rules, you’ll be better equipped to interact with the Arweave decentralized web, whether you’re a developer or an end user.
Making Deployment a Breeze with 4EVERLAND
If you’ve been grappling with a more complicated deployment method, we’ve got good news for you — there’s an easier way. Allow us to introduce 4EVERLAND, a straightforward and efficient platform for all your deployment needs.
It’s key to mention that 4EVERLAND employs Manifests in its Arweave deployment process, ensuring it’s in full alignment with industry best practices.
In the tutorial below, we present a clear, step-by-step guide to help you deploy your website or project to Arweave using 4EVERLAND. To make the process even more user-friendly, we’ve included helpful screenshots for each step:
Initiate the Process & Account Linking. Begin by navigating to the ‘Hosting’ section. Once there, proceed to ‘Projects’, then connect your 4EVERLAND account with GitHub. This integration will allow for seamless project deployment.
Import Your Repository. Once your account is connected, you will have the option to import the repository you wish to deploy. Select the desired repo.
Configuration Settings
Move on to ‘Step 2’.
Adjust the necessary configurations as per your requirements.
Ensure you select ‘Arweave’ as your hosting platform.
Deployment
Once all settings are in place, click on the ‘Deploy’ button. After a successful deployment, your project will be live on Arweave!
Review and Access
To view the status of your project, click on ‘Project Details’.
If you wish to directly visit your deployed project, simply click on the ‘Visit’ button or link.
Here is the demonstration of the deployed project
You can also access the deployed project using the following URL path format: https://arweave.net/FxmMc7CUkurIELUU8icITK51alXOVpD0mBrmaxPL4sU/index.html
This is what a completed deployment folder directory looks like
Automatically Generated Manifest File Showcase
As we wrap up this tutorial, it’s essential to note that there’s more than one way to achieve your Arweave deployment goals. Aside from using automated hosting services, you have the option to manually create your website and generate a Manifest file. Once the Manifest is prepared, you can use 4EVERLAND’s bucket feature to deploy it to Arweave. The end result is essentially the same.
Thank you for following this tutorial, and we wish you success in all your future Arweave deployments, whether you choose automated hosting or take the manual route with Manifests.
About 4EVERLAND
4EVERLAND is a Web3 infrastructure powered by blockchain technology that provides developers with convenient, efficient, and low-cost storage, network, and computing capabilities. It is committed to helping developers smoothly transition from Web2.0 to Web3.0 and building a Web3.0 cloud computing platform friendly to Web2.0.
Website | Twitter | Telegram | Discord | Reddit | Medium | Email
