Skip to content

Commit 5409cbe

Browse files
achingbrainachingbrain
committed
chore: initial import
0 parents  commit 5409cbe

File tree

15 files changed

+730
-0
lines changed

15 files changed

+730
-0
lines changed

‎.github/dependabot.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: npm
4+
directory: "/"
5+
schedule:
6+
interval: daily
7+
time: "11:00"
8+
open-pull-requests-limit: 50

‎.github/workflows/ci.yml

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- '**'
10+
11+
concurrency:
12+
group: ${{ github.head_ref || github.ref_name }}
13+
cancel-in-progress: true
14+
15+
jobs:
16+
examples:
17+
runs-on: ubuntu-latest
18+
name: Test ${{ matrix.project }}
19+
strategy:
20+
fail-fast: false
21+
matrix:
22+
project:
23+
- js-libp2p-example-auto-relay
24+
- js-libp2p-example-chat
25+
defaults:
26+
run:
27+
working-directory: examples/${{ matrix.project }}
28+
steps:
29+
- uses: actions/checkout@v3
30+
- uses: actions/setup-node@v3
31+
with:
32+
node-version: lts/*
33+
- name: Install dependencies
34+
run: npm install
35+
- name: Install Playwright
36+
run: npx -y playwright install --with-deps
37+
- name: Run tests
38+
run: npm run test
39+
env:
40+
CI: true
41+
42+
monorepo:
43+
runs-on: ubuntu-latest
44+
name: Test monorepo
45+
steps:
46+
- uses: actions/checkout@v3
47+
- uses: actions/setup-node@v3
48+
with:
49+
node-version: lts/*
50+
- name: Install dependencies
51+
run: npm install
52+
- name: Install Playwright
53+
run: npx -y playwright install --with-deps
54+
- name: Run linting
55+
run: npm run lint
56+
env:
57+
CI: true
58+
- name: Run tests
59+
run: npm run test
60+
env:
61+
CI: true
62+
63+
push-changes:
64+
name: Push changes
65+
runs-on: ubuntu-latest
66+
needs: [monorepo, examples]
67+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
68+
strategy:
69+
fail-fast: true
70+
matrix:
71+
project:
72+
- js-libp2p-example-auto-relay
73+
- js-libp2p-example-chat
74+
steps:
75+
- uses: convictional/trigger-workflow-and-wait@f69fa9eedd3c62a599220f4d5745230e237904be
76+
with:
77+
owner: libp2p
78+
repo: ${{ matrix.project }}
79+
github_token: ${{ secrets.REPO_PULL_TOKEN }}
80+
workflow_file_name: sync.yml

‎.gitignore

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
node_modules
2+
build
3+
dist
4+
.docs
5+
.coverage
6+
node_modules
7+
package-lock.json
8+
yarn.lock
9+
.DS_Store
10+
.next
11+
.vscode
12+
test-results
13+
playwright-report
14+
.parcel-cache
15+
.envrc
16+
.tool-versions

‎CONTRIBUTING.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Contributing <!-- omit in toc -->
2+
3+
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.
4+
5+
## Table of Contents <!-- omit in toc -->
6+
7+
- [Howto](#howto)
8+
- [How to add a new example](#how-to-add-a-new-example)
9+
- [Examples must](#examples-must)
10+
- [Update `js-libp2p` to run tests against the repo](#update-js-libp2p-to-run-tests-against-the-repo)
11+
12+
13+
## Howto
14+
15+
1. Fork the IPFS Examples Project (`https://github.com/libp2p/js-libp2p-examples`)
16+
2. Create your Feature Branch (`git checkout -b feature/amazing-feature`)
17+
3. Commit your Changes (`git commit -a -m 'feat: add some amazing feature'`)
18+
4. Push to the Branch (`git push origin feature/amazing-feature`)
19+
5. Open a Pull Request
20+
21+
## How to add a new example
22+
23+
1. Decide on a pithy folder name for your example, it should start with `js-libp2p-example-` and ideally be one or two words that describe what it's about - e.g. `js-libp2p-example-transfer-files`
24+
1. Create a folder in this repo under `examples`, eg. `./examples/js-libp2p-example-transfer-files`
25+
1. Add the files and tests that make up the example
26+
1. Add the folder name to the `project-list` lists in the `examples` and `push-changes` jobs in this repositories `./github/ci.yml`
27+
1. Create a PR to https://github.com/libp2p/github-mgmt similar to https://github.com/libp2p/github-mgmt/pull/22 to facilitate the addition of your project as an isolated repo.
28+
29+
## Examples must
30+
31+
- Live inside the `/examples/` folder
32+
- Have tests and should make use of `test-ipfs-example` library
33+
- Implement the following scripts:
34+
- `clean`: used to clean all the unnecessary code (e.g.: files generated by bundlers and package managers)
35+
- `build`: used to build the example
36+
- `start`: used to start the example
37+
- `test`: used to test the example
38+
- The `README.md` must have (see example inside `example-template`):
39+
- Link to `Codesandbox.com` for one-click running demonstration
40+
- References for documentation/tutorials used to build the example
41+
- _Optional:_ Screenshots, gifs, etc... under `img/` folder
42+
- Update the CI to run the tests of the new example as standalone
43+
- Edit `github/workflows/ci.yml`
44+
- Add the test name to `project` under `matrix`
45+
46+
## Update `js-libp2p` to run tests against the repo
47+
48+
Open a PR to the [libp2p/js-libp2p](https://github.com/libp2p/js-libp2p) project that edits the `.github/workflows/examples.yml` in order to make sure a libp2p release does not break your new example.
49+
50+
Search `.github/workflows/test.yml` for the `test-examples` section and add a block at the end of the `example` matrix key similar to:
51+
52+
```yml
53+
- name: my super fun new example
54+
repo: https://github.com/libp2p/js-libp2p-my-super-fun-new-example.git
55+
deps: libp2p@$PWD/packages/libp2p/dist
56+
```
57+
58+
The value of the `deps` key will vary depending on which modules from Helia your example uses. Above we override the `helia` module, but your example may different deps.
59+
60+
Please see the existing setup in `.github/workflows/test.yml` for how to ensure you are overriding the correct modules.

‎README.md

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
<p align="center">
2+
<a href="https://libp2p.io">
3+
<img width="250" src="https://github.com/libp2p/js-libp2p/blob/master/img/libp2p.png?raw=true" alt="libp2p hex logo" />
4+
</a>
5+
</p>
6+
7+
<h3 align="center">A collection of js-libp2p examples</h3>
8+
9+
<p align="center">
10+
<img src="https://raw.githubusercontent.com/jlord/forkngo/gh-pages/badges/cobalt.png" width="200">
11+
<br>
12+
<a href="https://github.com/libp2p/js-libp2p/tree/master/doc">Explore the docs</a>
13+
·
14+
<a href="https://github.com/libp2p/js-libp2p-examples/issues">Report Bug</a>
15+
·
16+
<a href="https://github.com/libp2p/js-libp2p-examples/issues">Request Feature/Example</a>
17+
</p>
18+
19+
## Table of Contents
20+
21+
- [Table of Contents](#table-of-contents)
22+
- [About The Project](#about-the-project)
23+
- [Getting Started](#getting-started)
24+
- [Examples](#examples)
25+
- [Understanding how libp2p works](#understanding-how-libp2p-works)
26+
- [Other examples](#other-examples)
27+
- [libp2p in the Browser](#libp2p-in-the-browser)
28+
- [Prerequisites](#prerequisites)
29+
- [Documentation](#documentation)
30+
- [Want to hack on IPFS?](#want-to-hack-on-ipfs)
31+
32+
## About The Project
33+
34+
- Read the [docs](https://ipfs.github.io/helia/modules/helia.html)
35+
- Look into other [examples](https://github.com/libp2p/js-libp2p-examples) to learn how to spawn a Helia node in Node.js and in the Browser
36+
- Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it
37+
- Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs
38+
- Check out https://docs.ipfs.io for tips, how-tos and more
39+
- See https://blog.ipfs.io for news and more
40+
- Need help? Please ask 'How do I?' questions on https://discuss.ipfs.io
41+
42+
## Getting Started
43+
44+
### Examples
45+
46+
Feel free to jump directly into the examples, however going through the following sections will help build context and background knowledge.
47+
48+
#### Understanding how libp2p works
49+
50+
- [Circuit Relay](./examples/js-libp2p-example-circuit-relay)
51+
52+
#### Other examples
53+
54+
- Running libp2p in the Electron (future)
55+
- [The standard echo net example with libp2p](./echo)
56+
- [A simple chat app with libp2p](./chat)
57+
58+
#### libp2p in the Browser
59+
There are a number of ways libp2p can be used in the browser. Here are some examples:
60+
61+
- [webRTC](./libp2p-in-the-browser/webrtc/README.md)
62+
- [websockets](./libp2p-in-the-browser/websockets/README.md)
63+
- [webtransport](./libp2p-in-the-browser/webtransport/README.md)
64+
65+
There is also an tutorial of how all of these transports can be [universally connected](https://github.com/libp2p/universal-connectivity/tree/main)
66+
67+
### Prerequisites
68+
69+
Make sure you have installed all of the following prerequisites on your development machine:
70+
71+
- Git - [Download & Install Git](https://git-scm.com/downloads). OSX and Linux machines typically have this already installed.
72+
- Node.js - [Download & Install Node.js](https://nodejs.org/en/download/) and the npm package manager.
73+
74+
## Documentation
75+
76+
- [IPFS Primer](https://dweb-primer.ipfs.io/)
77+
- [IPFS Docs](https://docs.ipfs.io/)
78+
- [Tutorials](https://proto.school)
79+
- [More examples](https://github.com/libp2p/js-libp2p-examples)
80+
- [API - Helia](https://ipfs.github.io/helia/modules/helia.html)
81+
- [API - @helia/unixfs](https://ipfs.github.io/helia-unixfs/modules/helia.html)
82+
83+
## Want to hack on IPFS?
84+
85+
[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)
86+
87+
The IPFS implementation in JavaScript needs your help! There are a few things you can do right now to help out:
88+
89+
Read the [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md) and [JavaScript Contributing Guidelines](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md).
90+
91+
- **Check out existing issues** The [issue list](https://github.com/ipfs/helia/issues) has many that are marked as ['help wanted'](https://github.com/ipfs/helia/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) or ['difficulty:easy'](https://github.com/ipfs/helia/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Adifficulty%3Aeasy) which make great starting points for development, many of which can be tackled with no prior IPFS knowledge
92+
- **Look at the [Helia Roadmap](https://github.com/ipfs/helia/blob/main/ROADMAP.md)** This are the high priority items being worked on right now
93+
- **Perform code reviews** More eyes will help
94+
a. speed the project along
95+
b. ensure quality, and
96+
c. reduce possible future bugs
97+
- **Add tests**. There can never be enough tests

‎examples/js-libp2p-example-circuit-relay/LICENSE

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
This project is dual licensed under MIT and Apache-2.0.
2+
3+
MIT: https://www.opensource.org/licenses/mit
4+
Apache-2.0: https://www.apache.org/licenses/license-2.0

‎examples/js-libp2p-example-circuit-relay/LICENSE-APACHE

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
2+
3+
http://www.apache.org/licenses/LICENSE-2.0
4+
5+
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

‎examples/js-libp2p-example-circuit-relay/LICENSE-MIT

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
The MIT License (MIT)
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy
4+
of this software and associated documentation files (the "Software"), to deal
5+
in the Software without restriction, including without limitation the rights
6+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7+
copies of the Software, and to permit persons to whom the Software is
8+
furnished to do so, subject to the following conditions:
9+
10+
The above copyright notice and this permission notice shall be included in
11+
all copies or substantial portions of the Software.
12+
13+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19+
THE SOFTWARE.

0 commit comments

Comments
 (0)