Skip to content

Commit 7f4ca5a

Browse files
macrogregmacrogreg
authored
Instructions for running as Dev and release Manifest artifacts (#2)
* Add instructions on how to run locally to the readme * Ensure Manifest is valid * Ensure Manifest is deployed along with the app to the web, pointing to the correct app URL * Ensure that Manifest pointing to the correct app URL is made available as a Release build artifact
2 parents c90b12f + a090b1b commit 7f4ca5a

File tree

8 files changed

+210
-61
lines changed

8 files changed

+210
-61
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,13 +79,13 @@ quasar build
7979
# Office-specific commands
8080
npm run office-start # Start debugging in Excel
8181
npm run office-stop # Stop debugging session
82-
npm run office-validate # Validate manifest.xml
82+
npm run office-validate # Validate `ExpLens.Excel-AddIn.Manifest.Local.xml`
8383
```
8484

8585
### Environment & Configuration
8686

8787
- Quasar config in `quasar.config.ts` with custom build env vars from `package.json` (version, name, etc.)
88-
- Dev server runs on `http://localhost:9000` (referenced in `manifest.xml`)
88+
- Dev server runs on `http://localhost:9000` (referenced in `ExpLens.Excel-AddIn.Manifest.Local.xml`)
8989
- Vue Router uses **hash mode** to avoid Office.js history issues
9090
- TypeScript with strict mode enabled
9191

‎.github/workflows/release.yml‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,12 +75,42 @@ jobs:
7575
mkdir -p "docs/app/current/excel"
7676
cp -r dist/spa/* "docs/app/current/excel/"
7777
78+
- name: Prepare Manifest for the Current dir
79+
continue-on-error: true
80+
run: |
81+
# Copy manifest file
82+
if [ ! -f "ExpLens.Excel-AddIn.Manifest.Local.xml" ]; then
83+
echo "Error: Source manifest file not found: ExpLens.Excel-AddIn.Manifest.Local.xml"
84+
exit 1
85+
fi
86+
87+
cp "ExpLens.Excel-AddIn.Manifest.Local.xml" "docs/app/current/excel/ExpLens.Excel-AddIn.Manifest.xml"
88+
89+
if [ ! -f "docs/app/current/excel/ExpLens.Excel-AddIn.Manifest.xml" ]; then
90+
echo "Error: Failed to copy manifest file to 'docs/app/current/excel/ExpLens.Excel-AddIn.Manifest.xml'"
91+
exit 1
92+
fi
93+
94+
# Replace localhost URL with production URL
95+
sed -i 's|http://localhost:9000|https://explens.app|g' "docs/app/current/excel/ExpLens.Excel-AddIn.Manifest.xml"
96+
97+
echo "Manifest for 'current' deployment prepared successfully"
98+
99+
- name: Upload Manifest Artifact for the Current dir
100+
continue-on-error: true
101+
uses: actions/upload-artifact@v4
102+
with:
103+
name: ExpLens.Excel-AddIn.Manifest.xml
104+
path: docs/app/current/excel/ExpLens.Excel-AddIn.Manifest.xml
105+
retention-days: 90
106+
compression-level: 0
107+
78108
- name: Build project for Version Dir
79109
run: |
80110
VERSION=${{ steps.version.outputs.version }}
81111
npm run build --qPublicBasePath=app/$VERSION/excel
82112
83-
- name: Release to version dir
113+
- name: Release to Version dir
84114
run: |
85115
VERSION=${{ steps.version.outputs.version }}
86116
# Create version directory
@@ -91,6 +121,40 @@ jobs:
91121
# Copy dist/spa to docs/app/version/excel
92122
cp -r dist/spa/* "docs/app/$VERSION/excel/"
93123
124+
- name: Prepare Manifest for the Version dir
125+
continue-on-error: true
126+
run: |
127+
VERSION=${{ steps.version.outputs.version }}
128+
# Copy manifest file
129+
if [ ! -f "ExpLens.Excel-AddIn.Manifest.Local.xml" ]; then
130+
echo "Error: Source manifest file not found: ExpLens.Excel-AddIn.Manifest.Local.xml"
131+
exit 1
132+
fi
133+
134+
cp "ExpLens.Excel-AddIn.Manifest.Local.xml" "docs/app/$VERSION/excel/ExpLens.Excel-AddIn.Manifest.v_$VERSION.xml"
135+
136+
if [ ! -f "docs/app/$VERSION/excel/ExpLens.Excel-AddIn.Manifest.v_$VERSION.xml" ]; then
137+
echo "Error: Failed to copy manifest file to 'docs/app/$VERSION/excel/ExpLens.Excel-AddIn.Manifest.v_$VERSION.xml'"
138+
exit 1
139+
fi
140+
141+
# Replace localhost URL with production URL
142+
sed -i 's|http://localhost:9000|https://explens.app|g' "docs/app/$VERSION/excel/ExpLens.Excel-AddIn.Manifest.v_$VERSION.xml"
143+
144+
# Replace 'current' path with version-specific path
145+
sed -i "s|app/current/|app/$VERSION/|g" "docs/app/$VERSION/excel/ExpLens.Excel-AddIn.Manifest.v_$VERSION.xml"
146+
147+
echo "Manifest for 'version' deployment ($VERSION) prepared successfully"
148+
149+
- name: Upload Manifest Artifact for the Version dir
150+
continue-on-error: true
151+
uses: actions/upload-artifact@v4
152+
with:
153+
name: ExpLens.Excel-AddIn.Manifest.v_${{steps.version.outputs.version}}.xml
154+
path: docs/app/${{steps.version.outputs.version}}/excel/ExpLens.Excel-AddIn.Manifest.v_${{steps.version.outputs.version}}.xml
155+
retention-days: 90
156+
compression-level: 0
157+
94158
- name: Commit and push changes
95159
env:
96160
PUSH_BRANCH: ${{ github.event.workflow_run.head_branch || github.ref_name }}

manifest.xml renamed to ExpLens.Excel-AddIn.Manifest.Local.xml

Lines changed: 22 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -6,28 +6,26 @@
66
xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides"
77
xsi:type="TaskPaneApp">
88
<Id>CC923F2C-0638-4F36-9E18-A4910CD71B74</Id>
9-
<Version>0.1.0.0</Version>
10-
<ProviderName>macrogreg</ProviderName>
9+
<Version>1.0.0</Version>
10+
<ProviderName>Advanced Personal Finance</ProviderName>
1111
<DefaultLocale>en-US</DefaultLocale>
12-
<DefaultSettings>
13-
<SourceLocation DefaultValue="http://localhost:9000/index.html"/>
14-
<RequestedWidth>500</RequestedWidth>
15-
</DefaultSettings>
16-
<DisplayName DefaultValue="ExpLens Excel-AddIn"/>
17-
<Description DefaultValue="Advanced analysis of personal finances (multiple dimensions). Automatically import up to 2 years of bank transactions (via the Lunch Money app)."/>
18-
<FormSettings></FormSettings>
19-
<Permissions>ReadWriteDocument</Permissions>
20-
21-
<IconUrl DefaultValue="http://localhost:9000/icons/favicon-32x32.png"/>
22-
<HighResolutionIconUrl DefaultValue="http://localhost:9000/icons/favicon-64x64.png"/>
23-
<SupportUrl DefaultValue="https://ToDo"/>
12+
<DisplayName DefaultValue="ExpLens"/>
13+
<Description DefaultValue="Analyze personal finances like a Pro (many categories). Auto-Import 2+ years of bank transactions (via LunchMoney)."/>
14+
<IconUrl DefaultValue="https://explens.app/images/favicon-32x32.png"/>
15+
<HighResolutionIconUrl DefaultValue="https://explens.app/images/favicon-64x64.png"/>
16+
<SupportUrl DefaultValue="https://explens.app"/>
2417
<AppDomains>
18+
<AppDomain>https://explens.app</AppDomain>
2519
<AppDomain>https://lunchmoney.app</AppDomain>
2620
<AppDomain>https://github.com</AppDomain>
2721
</AppDomains>
2822
<Hosts>
2923
<Host Name="Workbook"/>
3024
</Hosts>
25+
<DefaultSettings>
26+
<SourceLocation DefaultValue="http://localhost:9000/app/current/excel/index.html"/>
27+
</DefaultSettings>
28+
<Permissions>ReadWriteDocument</Permissions>
3129

3230
<VersionOverrides
3331
xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides"
@@ -65,7 +63,6 @@
6563
</Icon>
6664
<Action xsi:type="ShowTaskpane">
6765
<TaskpaneId>EL.Taskpain-Id</TaskpaneId>
68-
<Title resid="Taskpain-Title" />
6966
<SourceLocation resid="Taskpane-Url"/>
7067
</Action>
7168
</Control>
@@ -77,24 +74,24 @@
7774
</Hosts>
7875
<Resources>
7976
<bt:Images>
80-
<bt:Image id="Icon.16x16" DefaultValue="http://localhost:9000/icons/favicon-16x16.png"/>
81-
<bt:Image id="Icon.32x32" DefaultValue="http://localhost:9000/icons/favicon-32x32.png"/>
82-
<bt:Image id="Icon.80x80" DefaultValue="http://localhost:9000/icons/favicon-80x80.png"/>
77+
<bt:Image id="Icon.16x16" DefaultValue="https://explens.app/images/favicon-16x16.png"/>
78+
<bt:Image id="Icon.32x32" DefaultValue="https://explens.app/images/favicon-32x32.png"/>
79+
<bt:Image id="Icon.80x80" DefaultValue="https://explens.app/images/favicon-80x80.png"/>
8380
</bt:Images>
8481
<bt:Urls>
85-
<bt:Url id="GetStarted-LearnMoreUrl" DefaultValue="https://ToDo"/>
86-
<bt:Url id="Taskpane-Url" DefaultValue="http://localhost:9000/index.html"/>
82+
<bt:Url id="GetStarted-LearnMoreUrl" DefaultValue="https://explens.app"/>
83+
<bt:Url id="Taskpane-Url" DefaultValue="http://localhost:9000/app/current/excel/index.html"/>
8784
</bt:Urls>
8885
<bt:ShortStrings>
89-
<bt:String id="GetStarted-Title" DefaultValue="Bank Transactions Sync"/>
90-
<bt:String id="TabGroup-Label" DefaultValue="ExpLens"/>
91-
<bt:String id="ShowPaneButton-Label" DefaultValue="Show Pane"/>
86+
<bt:String id="GetStarted-Title" DefaultValue="ExpLens"/>
87+
<bt:String id="TabGroup-Label" DefaultValue="Finances"/>
88+
<bt:String id="ShowPaneButton-Label" DefaultValue="ExpLens"/>
9289
<bt:String id="ShowPaneButton-Tip-Title" DefaultValue="Show ExpLens Task Pane"/>
9390
<bt:String id="Taskpain-Title" DefaultValue="ExpLens"/>
9491
</bt:ShortStrings>
9592
<bt:LongStrings>
96-
<bt:String id="ShowPaneButton-Tip-Description" DefaultValue="Click to show the ExpLens task pane. Synchronize your Bank Transactions from there."/>
97-
<bt:String id="GetStarted-Description" DefaultValue="Analyze your finances. Synchronize Bank Transactions with Lunch Money. To view: [HOME tab] > [ExpLens] > [Show Pane]."/>
93+
<bt:String id="GetStarted-Description" DefaultValue="Analyze your finances. Import 2+ years of bank transactions. To view: [HOME tab] > [Finances] > [ExpLens]."/>
94+
<bt:String id="ShowPaneButton-Tip-Description" DefaultValue="Click to show the ExpLens task pane. Synchronize your Bank Transactions from there."/>
9895
</bt:LongStrings>
9996
</Resources>
10097
</VersionOverrides>

‎README.md‎

Lines changed: 78 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@ ExpLens Excel-AddIn
66

77
### Intent
88

9-
This project enables people to work with their financial data freely and effectively, without restrictions. However, to protect the effort invested in building and maintaining it, commercial/competitive use is restricted.
9+
This project enables people to work with their financial data freely and effectively, without restrictions.
10+
However, to protect the effort invested in building and maintaining it, commercial/competitive use is restricted.
1011

1112
**Interested in commercial use?
1213
Reach out! We'll work out reasonable terms.**
@@ -24,26 +25,89 @@ See [LICENSE.md](./LICENSE.md) for complete terms.
2425
- ✗ Building competing commercial products/services: _not allowed_.
2526
- ✗ Selling or hosting as a service: _not allowed_.
2627

27-
_Disclaimer: The authors and contributors accept no responsibility, direct or indirect, for any consequences from using this project._
28+
_Disclaimer: The authors and contributors accept no responsibility, direct or indirect, for any consequences from
29+
using this project._
2830

2931
## Developer guide
3032

31-
(This section is work in progress.)
33+
(If some info was missing and you needed to figure it out, please create a pull request to add it here.)
3234

3335
#### Install
3436

35-
```bash
36-
npm install
37-
```
37+
Clone the repo. Then:
3838

39-
#### Start the app in development mode (hot-code reloading, error reporting, etc.)
39+
`npm install` or `npm ci`
4040

41-
```bash
42-
quasar dev
43-
```
41+
#### Build and start locally
4442

45-
#### Build the app for production
43+
`npm run dev --qPublicBasePath=app/current/excel`
44+
(this invokes `quasar dev` and passes a parameter to set the URL base the way Excel expects it)
4645

47-
```bash
48-
quasar build
49-
```
46+
Quasar will build the app and host it under `http://localhost:9000/app/current/excel/`.
47+
Note: if port 9000 is taken, Quasar might silently choose another port. However, Excel will look for ExpLens on
48+
port 9000. If you need to use another port, make sure to modify the manifest accordingly
49+
(`ExpLens.Excel-AddIn.Manifest.xml`).
50+
51+
##### Build for production
52+
53+
`quasar build` or `npm run build --qPublicBasePath=url/base/path`
54+
55+
#### Activate the Excel Add-In
56+
57+
The _release_ version of ExpLens works on Excel Web and Excel Desktop (Windows & Mac).
58+
59+
The instructions here are for the _dev_ version (Windows desktop).
60+
61+
##### Option 1: "Admin Style" (easer to uninstall)
62+
63+
1. Share the root folder of your cloned repo as a local network drive.
64+
E.g., if you cloned into `c:\Code\ExpLens\` and your machine is called `DEV-PC`, then your share might be
65+
called `\\DEV-PC\ExpLens`.
66+
67+
2. In Excel, add the network share as a trusted Add-In Catalog:
68+
- Go to: _File_ > _Options_ > _Trust Center_ > _Trust Center Settings_ > _Trusted Add-In Catalogs_.
69+
- In _Catalog Url_, enter the address of your file share
70+
(e.g., `\\DEV-PC\ExpLens`).
71+
- Click _Add catalog_, select _Show in menu_, OK all dialogs, and restart Excel (make sure to close all windows).
72+
73+
3. Activate the Add-In:
74+
_Home_ > _Add-ins_ > _More Add-ins_. At the top you will have a _Shared Folder_ option. When you select it, you
75+
will see the ExpLens add-in in the list. Install it.
76+
77+
The Add-In will start and attempt to load from
78+
`http://localhost:9000/app/current/excel/`
79+
80+
(See section 'Build and start locally' above.)
81+
82+
###### Uninstalling:
83+
84+
Return to _Trusted Add-In Catalogs_, remove the shared repo directory, conform, and restart Excel (all windows).
85+
86+
##### Option 2: "Dev Style" (easer to get started)
87+
88+
1. Clone the repo and install packages.
89+
(see above)
90+
91+
2. Build and start the dev server.
92+
(see above)
93+
94+
3. Install the manifest using the Office AddIn tool:
95+
`npm run office-start`
96+
This will put some settings into the registry and open Excel with the Add-In loaded.
97+
98+
The Add-In will start and attempt to load from
99+
`http://localhost:9000/app/current/excel/`
100+
101+
(See section 'Build and start locally' above.)
102+
103+
###### Uninstalling:
104+
105+
If you thought this was easier than the "Admin Style", then you have not yet tried to uninstall the
106+
Add-In (which is a normal par of the dev process).
107+
If you time it well, then this will do it:
108+
`npm run office-stop`
109+
110+
But some of the time the state required for the tool to correctly know how to uninstall is lost, and you have to
111+
go to the registry. The add-ins are listed under:
112+
`Computer\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\Developer`.
113+
Find the one you want to remove, and delete all associated entries (there are several).

‎package.json‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "exp-lens-excel-addin",
3-
"version": "0.0.1",
3+
"version": "0.0.2",
44
"description": "ExpLens Excel-AddIn",
55
"productName": "ExpLens Excel-AddIn",
66
"author": "macrogreg <[email protected]>",
@@ -13,6 +13,7 @@
1313
"format-check": "prettier --check \"**/*.{js,ts,vue,scss,html,md,json}\"",
1414
"test": "echo \"No test specified\" && exit 0",
1515
"dev": "quasar dev",
16+
"dev-current": "npm run dev --qPublicBasePath=app/current/excel",
1617
"build": "quasar build",
1718
"postinstall": "quasar prepare",
1819
"licenses:generate": "license-checker-rseidelsohn --production --markdown --out license/THIRD-PARTY-LICENSES.md",
@@ -22,9 +23,9 @@
2223
"office-prettier": "office-addin-lint prettier",
2324
"office-signin": "office-addin-dev-settings m365-account login",
2425
"office-signout": "office-addin-dev-settings m365-account logout",
25-
"office-start": "office-addin-debugging start manifest.xml",
26-
"office-stop": "office-addin-debugging stop manifest.xml",
27-
"office-validate": "office-addin-manifest validate manifest.xml"
26+
"office-start": "office-addin-debugging start ExpLens.Excel-AddIn.Manifest.Local.xml",
27+
"office-stop": "office-addin-debugging stop ExpLens.Excel-AddIn.Manifest.Local.xml",
28+
"office-validate": "office-addin-manifest validate ExpLens.Excel-AddIn.Manifest.Local.xml"
2829
},
2930
"dependencies": {
3031
"@quasar/extras": "^1.16.4",

0 commit comments

Comments
 (0)