Skip to content

Improve safari development documentation #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Hinton merged 4 commits into from
Dec 28, 2022
Merged

Improve safari development documentation #25

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0927a01
Improve safari development documentation
Hinton Dec 8, 2022
7134dd7
Minor wording changes
Hinton Dec 8, 2022
c57bcb0
Improve slightly
Hinton Dec 8, 2022
52120a5
Update docs/getting-started/clients/browser/index.md
Hinton Dec 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 41 additions & 30 deletions docs/getting-started/clients/browser/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,31 +64,57 @@ the Bitwarden heading in the Temporary Extensions page. To debug the popup:

### Safari

#### Resetting the extension reference paths
Safari WebExtensions must be distributed through the Mac App Store, bundled with a regular Mac App
Store application. Due to this the build and debug process is slightly different compared to the
other browsers.

On MacOS, the Browser extension is packaged with the Desktop client. If you’ve built, installed or
ran the Desktop client before (including the official release), there’s a risk that Safari will
continue to load the official Browser extension and not the version you’ve built from source.
#### Uninstall previous versions

To avoid this, follow the instructions below to “reset” Safari’s extension reference paths:
If you’ve built, installed or ran the Desktop client before (including the official release), Safari
will most likely continue to load the official Browser extension and not the version you’ve built
from source.

To avoid this, follow the instructions below to uninstall the Safari extension:

1. Open Safari
2. Click “Preferences” and then click the “Extensions” tab
3. Uninstall the Bitwarden extension
4. Quit and completely close Safari
5. If you have the official Desktop client installed, uninstall it
6. If you have previously built the Desktop client from source, delete the `PlugIns` directory (if
it exists) and the `.dmg` (if you ran the Mac Apple Store build)
7. Reopen Safari and check Preferences to confirm that there is no Bitwarden Browser extension
installed
8. Quit and completely close Safari
3. Click uninstall next to the Bitwarden extension
4. Delete the Application with the extension.
5. Reopen Safari and check Preferences to confirm that there is no Bitwarden Browser extension
installed. In case there still is a Bitwarden Extension please repeat step 3-4.
6. Quit and completely close Safari

You may need to do this periodically if you are loading the Browser extension from different sources
(for example, switching between a local build and the official release).

#### Testing
#### Developing in Xcode

The easiest way to develop the extension is to build and debug it using Xcode.

1. Build the extension:

```bash
npm run build:watch
```

2. Edit `build/manifest.json`. Move the `nativeMessaging` permission from the `optional_permissions`
section into the `permissions` section
3. Edit `build/index.html`, replace `<html class="__BROWSER__">` to `<html class="browser_safari">`.
Comment on lines +100 to +102
Copy link
Member

@MGibson1 MGibson1 Dec 28, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is fine for now, but we should automate this. https://bitwarden.atlassian.net/browse/TDL-215

Copy link
Member Author

@Hinton Hinton Dec 28, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know, I started looking into it and then couldn't be bothered.

Copy link
Member

@MGibson1 MGibson1 Dec 28, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yup, that's why I made a ticket 👍

4. Open `src/safari/desktop.xcodeproj` in Xcode
5. Run the "desktop" target.

:::note

Please remember to re-run through Xcode whenever any changes are made to the source files. It will
not automatically reload.

:::

To build and load the Browser extension:
#### Production build

The other alternative is to use the "proper" build process through gulp. This method doesn't require
any manual processing of the output since gulp does it for us. However we have to completely rebuild
the extension for every change, which is slower.

1. Build the extension for Safari

Expand Down Expand Up @@ -127,18 +153,3 @@ extension. It may be useful for debugging if you’re having difficulty.
:::

</bitwarden>

#### Developing in Xcode

You can also build and debug using Xcode, which allows for a more iterative approach without having
to wait a long time for the build to compile.

1. Build the extension:

```bash
npm run build
```

2. Edit `build/manifest.json`. Move the `nativeMessaging` permission from the
`optional_permissions` section into the `permissions` section
3. Open `src/safari/desktop.xcodeproj` in Xcode