Skip to content

Commit f48e48d

Browse files
PauloMFJPauloMFJ
authored
Merge pull request #1 from phantomstudios/feat/initial
Initial version
2 parents eb8aa39 + 05b3a46 commit f48e48d

18 files changed

+525
-111
lines changed

‎.github/CODEOWNERS‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
* @digitaljohn
1+
* @paulomfj @digitaljohn

‎.github/workflows/pr.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,10 @@ jobs:
2121
with:
2222
node-version: ${{ matrix.node-version }}
2323

24-
- name: npm install, build, and test
24+
- name: npm install, build
2525
run: |
2626
npm ci
2727
npm run build --if-present
2828
npm run lint
29-
npm test
3029
env:
3130
CI: true

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,11 @@ jobs:
2020
with:
2121
node-version: ${{ matrix.node-version }}
2222

23-
- name: npm install, build, and test
23+
- name: npm install, build
2424
run: |
2525
npm ci
2626
npm run build --if-present
2727
npm run lint
28-
npm test
2928
env:
3029
CI: true
3130

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ I'm really happy that you're interested in helping out with this little project.
44

55
As this is very early days for the project there's not a lot in the way of
66
resources, but please check out the [documentation](./README.md), and also the
7-
[list of issues](https://github.com/phantomstudios/PACKAGE-NAME/issues).
7+
[list of issues](https://github.com/phantomstudios/react-share/issues).
88

99
Please submit an issue if you need help with anything.
1010

@@ -20,7 +20,7 @@ pass. Testing is automated using GitHub Actions CI.
2020
## Submitting changes
2121

2222
Please send a
23-
[GitHub Pull Request to PACKAGE-NAME](https://github.com/phantomstudios/PACKAGE-NAME/pull/new/master)
23+
[GitHub Pull Request to react-share](https://github.com/phantomstudios/react-share/pull/new/master)
2424
with a clear list of what you've done (read more about
2525
[pull requests](https://help.github.com/en/articles/about-pull-requests)). When you send a pull
2626
request, please make sure you've covered off all the points in the template.
@@ -43,6 +43,6 @@ In effect this means:
4343
- Your Pull Request title and description become very important; they are the
4444
history of the master branch and explain all the changes.
4545
- You ought to be able to find any previous version easily using GitHub tabs, or
46-
[Releases](https://github.com/phantomstudios/PACKAGE-NAME/releases)
46+
[Releases](https://github.com/phantomstudios/react-share/releases)
4747

4848
Thanks, John Chipps-Harding

‎README.md‎

Lines changed: 200 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,230 @@
1-
# PACKAGE-NAME
1+
# react-share
22

33
[![NPM version][npm-image]][npm-url]
44
[![Actions Status][ci-image]][ci-url]
55
[![PR Welcome][npm-downloads-image]][npm-downloads-url]
66

7-
Package one-liner overview.
7+
An all-in-one React library to implement custom Page Sharing Meta and Social Media Sharing Buttons.
88

99
## Introduction
1010

11-
Package introduction, couple of paragraphs.
12-
13-
```javascript
14-
import useLibrary from "@phntms/PACKAGE-NAME";
15-
16-
const { something } = useLibrary({
17-
argument1: "something",
18-
argument2: "something else",
19-
});
20-
```
11+
Designed to use and extend [OpenGraph](https://ogp.me/) standards. Alongside, full sharing support to the following social media platforms; ... .
2112

2213
## Installation
2314

2415
Install this package with `npm`.
2516

2617
```bash
27-
npm i @phntms/PACKAGE-NAME
18+
npm i @phntms/react-share
2819
```
2920

3021
## Usage
3122

32-
Example 1 description.
23+
Example usage in Next.js:
3324

3425
```JSX
35-
import React from 'react';
36-
import useLibrary from '@phntms/PACKAGE-NAME';
37-
38-
const SomeExample = () = {
39-
const { something } = useApi({
40-
argument1: "something",
41-
argument2: "something else",
42-
});
43-
44-
return (
45-
<>
46-
<h1>Result</h2>
47-
<p>{something}</p>
48-
</>
49-
);
50-
}
26+
import { MetaHeadEmbed, TwitterHeadEmbed } from "@phntms/react-share";
27+
import type { AppProps } from "next/app";
28+
29+
const App = ({ Component }: AppProps) => (
30+
<>
31+
<Head>
32+
<MetaHeadEmbed
33+
titleTemplate="[siteTitle] | [pageTitle]"
34+
siteTitle="PHANTOM"
35+
pageTitle="Our Work"
36+
canonicalUrl="https://phantom.land/"
37+
pageURL="https://phantom.land/work/"
38+
description="Transforming challenges of all shapes and sizes into inventive, engaging and performance driven solutions that change the game."
39+
keywords={["creative-agency", "phantom", "work"]}
40+
imageUrl="https://bit.ly/3wiUOuk"
41+
imageAlt="PHANTOM logo."
42+
/>
43+
<TwitterHeadEmbed
44+
useLargeCard
45+
title="PHANTOM"
46+
description="Transforming challenges of all shapes and sizes into inventive, engaging and performance driven solutions that change the game."
47+
siteUsername="@phntmLDN"
48+
creatorUsername="@phntmLDN"
49+
/>
50+
</Head>
51+
<Component />
52+
</>
53+
);
54+
55+
export default App;
5156
```
5257

53-
Example 2 description.
58+
### &lt;MetaHeadEmbed />
5459

55-
```JSX
56-
import React from 'react';
57-
import useLibrary from '@phntms/PACKAGE-NAME';
58-
59-
const SomeExample2 = () = {
60-
const { something } = useApi({
61-
argument1: "something",
62-
argument2: "something else",
63-
});
64-
65-
return (
66-
<>
67-
<h1>Result</h2>
68-
<p>{something}</p>
69-
</>
70-
);
71-
}
60+
| Property | Type | Required | Notes |
61+
| ----------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
62+
| **pageTitle** | string | **Yes** | Every page should have a unique title that describes the page, such as 'Home', 'About' etc. |
63+
| **siteTitle** | string | **Yes** | Title of the site, usually the organization / brand name. |
64+
| **titleTemplate** | string | **No** | Title template used to display `pageTitle` and `siteTitle` in a template, displays the values using corresponding `[pageTitle]` and `[siteTitle]`. Example template: "[pageTitle] &#124; [siteTitle]". |
65+
| **description** | string | **Yes** | A one to two sentence description of your webpage. Keep it within 160 characters, and write it to catch the user's attention. |
66+
| **pageUrl** | string | **Yes** | Url of site page being shared. |
67+
| **canonicalUrl** | string | **Yes** | The canonical URL of your webpage that will be used as its default app URL. |
68+
| **keywords** | string&#124;string[] | **Yes** | List of SEO keywords describing what your webpage does. For example, `"your, tags"` or `["your", "tags"]`. |
69+
| **imageUrl** | string | **Yes** | Image url of asset to share. Recommended aspect ratio for landscape is 1.9:1 (1200x630) or for squares 1:1 (1200x1200). For more info, visit [here](https://iamturns.com/open-graph-image-size/). |
70+
| **imageAlt** | string | **Yes** | Image alt for users who are visually impaired. |
71+
| **locale** | string | **No** | The locale these tags are marked up in, such as; `en_GB`, `fr_FR` and `es_ES`. Defaults to `en_US`. |
72+
73+
To add all page meta properties, add `MetaHeadEmbed` to the `head` of the page.
74+
75+
**Note**: `imageUrl` and `canonicalUrl` must start with `https://`, else they won't work.
76+
77+
### &lt;TwitterHeadEmbed />
78+
79+
| Property | Type | Required | Notes |
80+
| ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
81+
| **useLargeCard** | boolean | **No** | Summary card type. If `true`, uses large card, and if `false` uses small card. Defaults to `false`. |
82+
| **title** | string | **Yes** | A concise title for the related content. |
83+
| **description** | string | **No** | A description that concisely summarizes the content as appropriate for presentation within a Tweet. Should not be the same as title. |
84+
| **siteUsername** | string | **No** | The Twitter @username the card should be attributed to. |
85+
| **creatorUsername** | string | **No** | The Twitter @username for the content creator / author. |
86+
| **imageUrl** | string | **No** | Image to show in card. Images must be less than 5MB in size. Supported file types; JPG, PNG, WEBP and GIF. |
87+
| **imageAlt** | string | **No** | Image alt for users who are visually impaired. Maximum 420 characters. |
88+
89+
`TwitterHeadEmbed` _should_ be used alongside `MetaHeadEmbed` for full sharing support.
90+
91+
**Note**: Image used should be different based on `useLargeCard`:
92+
93+
- For large cards, use a 2:1 aspect ratio (300x157 px minium or 4096x4096 px maximum).
94+
- For small cards, use a 1:1 aspect ratio (144x144 px minium or 4096x4096 px maximum).
95+
96+
### getFacebookUrl()
97+
98+
| Parameter | Type | Required | Notes |
99+
| --------- | ------ | -------- | -------------------------------- |
100+
| url | string | **Yes** | URL of shared webpage. |
101+
| quote | string | **No** | Quote to show in Facebook card. |
102+
| hashtag | string | **No** | Hashtag to show in Facebook card |
103+
104+
Basic component example usage:
105+
106+
```jsx
107+
import { getFacebookUrl } from "@phntms/react-share";
108+
109+
const ShareToFacebook = () => (
110+
<a
111+
href={getFacebookUrl({
112+
url: "https://www.npmjs.com/package/@phntms/react-share",
113+
})}
114+
>
115+
Share to Facebook
116+
</a>
117+
);
118+
119+
export default ShareToFacebook;
72120
```
73121

74-
## API
122+
### getLinkedinUrl()
123+
124+
| Parameter | Type | Required | Notes |
125+
| --------- | ------ | -------- | ------------------------------------------------------------------------ |
126+
| url | string | **Yes** | URL of shared webpage. |
127+
| title | string | **No** | Title to show in card. |
128+
| summary | string | **No** | Description to show in card |
129+
| source | string | **No** | Source of the content (for example... your website or application name). |
130+
131+
Basic component example usage:
132+
133+
```jsx
134+
import { getLinkedinUrl } from "@phntms/react-share";
135+
136+
const ShareToLinkedin = () => (
137+
<a
138+
href={getLinkedinUrl({
139+
url: "https://www.npmjs.com/package/@phntms/react-share",
140+
})}
141+
>
142+
Share to Linkedin
143+
</a>
144+
);
145+
146+
export default ShareToLinkedin;
147+
```
148+
149+
### getTwitterUrl()
150+
151+
| Parameter | Type | Required | Notes |
152+
| --------- | ------ | -------- | -------------------------------- |
153+
| url | string | **Yes** | URL of shared webpage. |
154+
| text | string | **No** | Text to show in Twitter card. |
155+
| hashtags | string | **No** | Hashtags to show in Twitter card |
156+
| related | string | **No** | Accounts to recommend following. |
157+
158+
Basic component example usage:
159+
160+
```jsx
161+
import { getTwitterUrl } from "@phntms/react-share";
162+
163+
const ShareToTwitter = () => (
164+
<a
165+
href={getTwitterUrl({
166+
url: "https://www.npmjs.com/package/@phntms/react-share",
167+
})}
168+
>
169+
Share to Twitter
170+
</a>
171+
);
172+
173+
export default ShareToTwitter;
174+
```
175+
176+
### getShareUrl()
177+
178+
If you would rather have all share urls in one place, `getShareUrl()` can be used! It includes props from every social platform listed above, so simply pass in a `SocialPlatform`, and the platforms corresponding props.
179+
180+
Example usage:
181+
182+
```jsx
183+
import { getShareUrl } from "@phntms/react-share";
184+
185+
const Share = () => (
186+
<a
187+
href={getShareUrl(SocialPlatforms.Facebook, {
188+
url: "https://www.npmjs.com/package/@phntms/react-share",
189+
})}
190+
>
191+
Share to Facebook
192+
</a>
193+
<a
194+
href={getShareUrl(SocialPlatforms.Linkedin, {
195+
url: "https://www.npmjs.com/package/@phntms/react-share",
196+
})}
197+
>
198+
Share to Linkedin
199+
</a>
200+
<a
201+
href={getShareUrl(SocialPlatforms.Twitter, {
202+
url: "https://www.npmjs.com/package/@phntms/react-share",
203+
})}
204+
>
205+
Share to Twitter
206+
</a>
207+
);
208+
209+
export default Share;
210+
```
211+
212+
## Further Resources
213+
214+
Useful resources for testing meta properties:
75215

76-
### Input
216+
- [Meta Tags](https://metatags.io/) - With Meta Tags you can preview how your webpage will look on Google, Facebook, Twitter and more.
217+
- [Social Share Preview](https://chrome.google.com/webstore/detail/social-share-preview/ggnikicjfklimmffbkhknndafpdlabib?hl=en) - Chrome browser extension to live preview how the webpage will look when shared. Especially useful for testing when app is auth protected.
77218

78-
- `argument1` : Required - Description of argument.
79-
- `argument2` : Optional - Description of argument.
219+
## 🍰 Requests and Contributing
80220

81-
### Output
221+
If a social media platform you want to use isn't already supported, or found an issue? Get involved! Please contribute using the GitHub Flow. Create a branch, add commits, and open a Pull Request or submit a new issue.
82222

83-
- `something`: Description of output.
223+
Please read `CONTRIBUTING` for details on our `CODE_OF_CONDUCT`, and the process for submitting pull requests to us!
84224

85-
[npm-image]: https://img.shields.io/npm/v/@phntms/PACKAGE-NAME.svg?style=flat-square&logo=react
86-
[npm-url]: https://npmjs.org/package/@phntms/PACKAGE-NAME
87-
[npm-downloads-image]: https://img.shields.io/npm/dm/@phntms/PACKAGE-NAME.svg
88-
[npm-downloads-url]: https://npmcharts.com/compare/@phntms/PACKAGE-NAME?minimal=true
89-
[ci-image]: https://github.com/phantomstudios/PACKAGE-NAME/workflows/test/badge.svg
90-
[ci-url]: https://github.com/phantomstudios/PACKAGE-NAME/actions
225+
[npm-image]: https://img.shields.io/npm/v/@phntms/react-share.svg?style=flat-square&logo=react
226+
[npm-url]: https://npmjs.org/package/@phntms/react-share
227+
[npm-downloads-image]: https://img.shields.io/npm/dm/@phntms/react-share.svg
228+
[npm-downloads-url]: https://npmcharts.com/compare/@phntms/react-share?minimal=true
229+
[ci-image]: https://github.com/phantomstudios/react-share/workflows/test/badge.svg
230+
[ci-url]: https://github.com/phantomstudios/react-share/actions

‎SUPPORT.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# PACKAGE-NAME Support
1+
# react-share Support
22

3-
For _questions_ on how to use `PACKAGE-NAME` or what went wrong when you tried something, our primary resource is by opening a
4-
[GitHub Issue](https://github.com/phantomstudios/PACKAGE-NAME/issues), where you can get help from developers.
3+
For _questions_ on how to use `react-share` or what went wrong when you tried something, our primary resource is by opening a
4+
[GitHub Issue](https://github.com/phantomstudios/react-share/issues), where you can get help from developers.

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)